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PREFACE 


“his manual.‘ documents the user | procedures for the 9900% Dewice- 


aN 


ors 
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Independent. File 1/0. Package. The. manual - is organized as” ‘follows: 


Section =I. provides a product overview of the Device Independent 
File t/o Package. 


“Section: If provides an. explanation of the concepts. implemented-. 
in’ this “package. ; ee 


Seetion III describes ‘the File I/O Decoder, .lists..the. entry” 
-. points into the decoder, ‘and’ presents a Pascal and assembly =: 
language calling sequence for each. | i 


Section IV «describes. the Interprocess Communciation (IPC) I/O~ 
Subsystem, defining» the. routines. that comprise this’ subsystém~ 
and. presenting Pascal’ and -assembly nenguage calling: i ad 
for: these: routines. | | 


‘Section Vv ‘describes the Encode .and Decode Routines - included. 
‘this -package. Each routine is documented » along — with Pree. 
assembly language calling sequence. 7 


Section VI describes configuration “of applications containing — 
SDIF I7O routines. Initialization .as well sas GOnENGUE St Ton: 
information is presented. 


Appendix A describes the Operator Interface (TO2) I/O. Subsystem - 
. demonstrating for .the Pascal user how to’write his‘own*I/O 
_, Subsystem. | | 


Appendix B provides pictures -of data structures used° -during~ 
I I/O applications. a | 


ee c defines the status codes returned by the File*I/O- | 
: Decoder. | : | _ 


-Apperidix D. defines the Dummy “1/0 Subsystem included © in-: this . 
- package. a : 


ee E describes the file.attributes that are defined - ‘during ~ 
access of File I/O Decoder routines. 


_ Appendix F presents listings of global declaration files for use 
by the: Pasca_ user in wcrking with this package: : 


The: following: publications offer informational. support’. to this 
documentzand' to:.users of this product. | 
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SECTION I 


OVERVIEW 


 -L.r GENERAL 


Texas: Instruments Device Independent File (DIF) 1/0 User’s Manual 
documents a collection of routines providing I/O services for the 9900 
family of microprocessors. This software enables Pascal and assembly. 
language users to perform device independent 1/0 utilizing a 
consistent file interface. Through the use of these routines, requests 
for.  f£ile services are automatically translated into calls to 
individual subsystems dedicated to managing data resident on various 
devices such as CRTs, card readers, printers, etc. 


‘The: DIF I/O package is especially useful when the performance of input 
and: output operations is required on any of several devices and the. 
‘specific device is not identifiable until run-time. Use of the DIF I/O 
package also enables the user to access a variety of software. 
subsystems using a single interface. ; 


In. addition to documenting software supplied by Texas Instruments, 
this manual presents standards that a user must follow to produce his 
own: subsystems with the capability to interface with this package and 
be accessed in a device independent manner. 


1.2. SOFTWARE 


The: software routines Gescribed in the Device Independent File I/0 
_ Package User”~s Manual are listed below. The Pascal versions of these 
routines are provided in the Microprocesor Pascal Executive contained 
in the Microprocessor Pascal System (TMSW753P and 754P). For the 
“assembly language user, these routines are provided in the Device 
- Independent File I/O Package (TMSW360D) | | 


e@ The File I/0 Decoder providing a device-independent 
interface between the user and a variety of I/O devices 
(floppy diskette, tape reader, printer, CRT, etc.). 


® The Interprocess Communication (IPC) I/0 Subsystem 
| implementing file-level message passing between processes. 


@ The Operator Interface I/O Subsystem (TO02) implementing 


data communication with terminals connected to a 9902 
asynchronous communications controller. 


“j-1 


@ Encode and Decode routines’ performing data conversion from 
the internal representation to printable format and 
conversely from printable format to internal 
representation. (These routines are used transparently in 
the Microprocessor Pascal Executive. However, the assembly 
language user calls these routines directly.) 


OW eR ry! 


1.3 HOST AND ‘TARGET ‘SYSTEMS . 


Development capabilities for applications using DIF 1/0 routines are 
provided by the following host systems: 


e Single-User FS990/4 or /10 floppy disk minicomputer with 

operating system software provided by the AMPLUS Software 

System and development system software provided by AMPLUS 
or the Microprocessor Pascal System. 


-@ Multi-user DS990/10 or /12 hard disc minicomputer with | 
operating system software provided by the DX Operating @2.. 
System and development system software provided by the DX 


system Or the Microprocessor Pascal System. eee 

sOC5 

varget systems include TMS9900 and TM990 Microprocessor systems. *2 *% 
suc. 5te 


— 


Device independent routines and data structures support I/O in. the 
target system. I/O in the host system is provided for in the-hest 


eyetem: Ss operating system. “Joes y 
aa | ore 

1.4' DIF 1/0 PACKAGE AS A COMPONENT eek eee 
5¢ Eq 


The DIF I/O is a member of Texas Instruments” 9900 series of eeneoncne 
software. This series contains a variety of individual software 


Products that can be separately purchased and combined with an 


application to produce a powerful software product. Because of the 
modularity of the routines comprising this product (as well as other 
Texas Instrument component software), the load module produced to run 
on a target will include only those "pieces" of the component that are 
required by the application. In this way, memory requirements are kept 
to the minimum. 


The Realtime Executive (see Subsection 1.5 below) acts as a software . 


link for an application written in one of several languages’ and 


utilizing various "components". Figure l-1l pictures this concept. The > 


Device Independent File I/O Package component is present along with 
two I/O Subsystem components. 
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FIGURE 1-1. COMPONENT SOFTWARE REPRESENTATION 


Led REQUIRED EXECUTIVE ENVIRONMENT 


Execution of the routines described in this document requires native 
code run-time support of an executive. (The executive provides control 
of the software execution in a computer system including control of 
CPU usage, memory uSage, routine calling conventions, data structures, 
etc.) Run-time support is provided for the assembly language 
programmer by Texas Instruments” Realtime Executive (TMSW330R) and for 
the Pascal user by the Microprocessor Pascal Executive (contained in 
the Microprocessor Pascal System - TMSW753P and 754P). These 
executives are described in the the Realtime Executive User”’s Manual 
(MP373) and in the Microprocessor Pascal Executive User’s Manual 
(MP385) respectively. | : | 
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SECTION II 
DEVICE INDEPENDENT FILE I/O SUBSYSTEM STANDARDS 


~2.1 GENERAL 


This section of the manual discusses the concept of device independent 
I/O .as it is implemented by this software and the standards which, 
‘when applied, allow the user to write his own subsystem to interface 
with this software. 


2..2 TERMINOLOGY 


Device Independent I/O refers to a mode of implementing input/output 
requests on target devices without naming the specific target device 
in the procedure call (a requirement when the appropriate device is 
mot identified until run time). As listed in Subsection 1.2, the 
routines translating device independent I/O requests into calls for a 
Particular device operation are contained in the File I/O Decoder. A 
Subsystem accessible to the File I/O Decoder and performing target I/O 
operations on the device is an I/O Subsystem. The logical connection 
between the CPU and the physical means of controlling a device is 
Called a Port. In most I/O Subsystems, the port identifies a 
particular device controller such as a 1TM990/303 Floppy Disk 
Controller. Each device controlled on the target is called a Node. The 
.- Node associated with the Floppy Disk Controller is a floppy disk. I/O 
\ -operations are executed sequentially in the order in which they are 
~ received. If, when a command is received, the calling process is 
suspended until all previously issued commands are completed, then 
Executed I/O is performed. Initiated I/O refers to instances when the 
calling process is reactivated before the command is completed. 


i 
\ 


2.3 1/0 SUBSYSTEM RATIONALE 


The I/O Subsytem Standards provide for the standardization of an 1/0 
interface in the user application. This standarization enables’ the 
user application to: | 


1) Realize a general file interface for I/O requests to 
various devices supported on the target system. Devices 
are treated as files. Requests for I/O services on the 
device are made as requests for file services. In this 
way, the Pascal user can use Pascal READLN and WRITELN 
statements to perform device I/O. The assembly language 
user can access the File I/O Decoder directly to perform 
device I/O. 


2) Implement initiated I/O, a means of servicing I/O requests 
without blocking the requesting process. 
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3) Activate muieipts ine Cences! of the Interface Handler (I/F. .»+3 
| Handler) manipulating the device on the target. 


4) Add various Interface Handlers and establish the means to 
communicate with them. The user can commuinicate with as 
Many devices (of varying types) as he requires. 


5) Access I/O service routines at varying levels of logical 


Orgainzation (from the logical file level to the physical 
device level). 


2-4 I/O MODEL 


An "I/O Model" adhering to the requirements of the I/O Subsystem | 


standards presented in this document is pictured in Figure 2-1 Senees 
This model is comprised of the following components: 


e The File I/0 Decoder translating user I/O requests to 
procedure calls for specific device services. 


@ Various I/O subsystems, each implementing the procedure 
calls from the File I/O Decoder for its specific device. 
An I/O Subsystem may be one of the component’ software 
packages that can be obtained from Texas Instruments (the 
File Manager and the Operator Interface I/O Subsystem are 
two examples), or can be written by the user to conform to 
the standards presented in this document. 


e Channels created to handle the communication from the I/0 
Subsystem to the Interface Handler software. ney 


@e The Interface Handler manipulating the device. — 


The components described above are ordered from a logical to. ‘a 
physical interface. This ordering traces the flow of program contral 
when device independent I/O is performed. The application generates 
I/O requests by invoking the File I/O Decoder . The Decoder selects 
the ee I/O Subsystem (File Manager, Operator Interface T/Q 
packages etc.) and passes control to that subsystem. The subsyste 

selects che appropriate device (floppy, printer, etc.) passing bsyatan 
to the associated Interface Handler. Movement of control between the 
levels is transparent (invisible) to the user. <A oat 
The user may choose the level at which he requires the request to .be 
executed. He may call the File I/O Decoder, the individual..f/ 
Subsystem, Or even the appropriate interface handler crom ckts 
application. However, it is only via the File I/O Decoder that calls 
os 1/0 routines can be performed without regard to a specific target 
evice. 


RO. 


Entering the I/O model below the File I/O Decoder Level (i.e., at. “the 
I/O Subsystem Level, Or at the Interface Handler level) requires (fhe 














foes 


user to understand the requirements associated with that lower level 
and to structure his code to meet those requirements../” a. 
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FIGURE 2-1. I/O MODEL 


NOTE: The above figure depvicts more than one Interface Handler 
attached to each I/O Subsystem. In actuality, an I/O Subsystem can 


Start a single Interface Handler several times to service different 
devices of the same type (e.g., the File Manager interfacing with. 
Several floppy disk controllers) or different Interface Handlers 
attached to different devices (¢.g., the File Manager interfacing with 
a” Lloppy disk controller and to a bubble memory controller). 


The remainder of this subsection describes each of the above 
components in detail. | : 


ies 


2.4.1 FILE I/0 DECODER 


Tire File I/0 Decoder provides the software capability for device 
independent I/O. The Pascal programmer uses such Pascal statements as 

SETNAME , RESET, REWRITE, READ, and WRITE to perform file I/O. These 
"Pascal primitives" in turn automatically access the File I/O Decoder 
wkthout any further user interface. The assembly language user 
application accesses the File I/O Decoder directly via file operation 
entry points (the Pascal user can also access these entry points 
ditectly) . Each entry point corresvonds to a device operation 
Supported on the target and is callable as a separate file service 
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sequences’ for. . the, 
presented in Section III. Among “tHe 


routine. The Pascal and assembly language calling 
File. [/0 Decoder routines are 


efitry points (callable routines) present are: 


-@ 
res 


DSINIT Initializes the File I/O Decoder and supported >”. a as 
| I/O Subsystems. st. 
DSCONNECT Connects a file pathname with an associated oe 
| I/O Subsystem and ultimately the physical ee 
device or node controlled by that subsystem. ~~__ 
DSCREATE Creates a file. veh 
DSOPEN Opens a file for access. pid 
D$ READ Initiates reading of a file. 2 EN 
DSWRITE Initiates writing to (or updating) a file. 
DSRDWAIT Reads a file; but delays return of control to nies 
calling routine until read operation is completed. 
DSWRWAIT Writes a file, but delays return of control to. ., 
calling routine until write operation is completed. 
DSPOSITION Resets the internal subsystem’s pointer to point. 
at the requested record. eS 
DSSTATUS Checks for status of oldest I/O request on the 
specified file at the File I/O Decoder Level. ae 
DSDSTATUS Checks for status of oldest I/O request on the. 
specified file at the subsystem level. 
DSABORTIO Aborts all I/O requests outstanding on a file. ~- 
DSCLOSE Closes a file disallowing further access until 
re-opened. ee 
DSDELETE Deletes a file. te 
DSDISCONNECT Severs the connection between a File pathname and 


harvey) 3 ae 


physical device as controlled by an I/O Subsystem. 


The operations requested via these entry points are viewed by the user 


on the File I/O Decoder level. At the point that 


called, 
particular device; 


In 


the user 


reality, 


these routines are 


need not associate the requested. operation with - ‘a 
the File I/O Decoder makes that association “f6r 
each file service accesses an entry point into “a 


device dependent service managed by the appropriate I/O Subsystem. | 


Two entry points in the File I/O Decoder bear special mention “eh 
DSCONNECT and DSDISCONNECT. i 


iat on ce 


Nol 
rer ee i" 
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BSCONNECT must be the first File [f/0 Decoder service ‘requested: (afte 
initialization) and is called to connect a specified file pathnamé 
(passed to DSCONNECT as a calling parameter) haa the appropriate 1/0 
Subsystem (and ultimately the device itself). "connect" time, the 
Filé “I/O Decoder will invoke each subsystem edt on the target in 
Succession until some subsystem recognizes the pathname parameter 
passed with the call. Such recognition is made because of the meaning 


attributed to the nodes making up the file pathname. For example, The 


File Manager I/O Subsystem recognizes the first node in the pathname 
as the name of ae volume it controls provided that volume has been 
previously installed via the File Manager’“s Install Volume command. 


NOTE: The possibility exists that a single file pathname can be 


Claimed by more than one I/O Subsystem. For this reason, the order in 
which individual I/O Subsystems are polled can be critical. 


When the pathname is recognized, internal data structures are created 
and maintained to sustain the connection between the file and the 
physical node or device, enabling the user to perform subsequent 
Qperations on the file. When no subsystem claims the pathname, an 
€rror condition is signalled. 

-A .call to DSDISCONNECT is performed to sever the association between 
"fhe file and the physical device. At "disconnect" time, the memory 
allocated for the data structures used to link the file to the 
physical node are returned to the System heap. 


The internal data structures referred to abov2 are illustrated in 


Appendix B. Each routine accessed in the File I/O Decoder is discussed | 


in detail in Section III. 


2.4.2 I/O Subsystems 


An I/O Subsystem is a collection of procedures managing a logically 


Similar set of I/O resources. Accessed through the File I/O Decoder, 
these resources are made available to file level users in a consistant 
manner invisible to the user. Examples of I/O Subsystems created by 
Texas Instruments are the 9900 File Manager (TMSW340F), the 
Interprocess Communication (IPC) Subsystem, and the Operator Interface 
(TO2) I/O Subsystem. 


‘the File I/O Decoder accesses I/O Subsystem routines via entry points 
“present in the I/O Subsystem. These entry points correspond to entry 
points present in the File I/O Decoder (i.e., the DSroutines described 
above in Subsection 2.4.1). The I/O Subsystem entry points are formed 
by . attaching a prefix (unique to the particular subsystem) to aie 
generic names of the file services. For example, READ is FMSREAD . i 

the. File Manager and TO2SREAD in the Operator Interface I/0 e payat cnt 


Because of its purpose, a particular I/O Subsystem may not support 
every file service for which it posseses entry points. For example, 
DELETE does not make sense in an I/O Subsystem managing a line 
Printer. These entry points are connected to stub (or dummy) routines. 
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If the user wishes, he can bypass the File I/O Decoder and can 
directly access the I/O Subsystem entry points. The I/O Subsystem 
reaction when each particular entry point is accessed (i.e., each file 
request is made) is general to all subsystems (with the exception of 


those file services that are not supported in a particular subsystem | 


as mentioned above). Thus the parameterization for | a given entry point 
type is the same across all subsystems. 


2.4.3 Channels 


Channels can be conceptualized as data structures over which messages. 


(data) can be sent and received. In the context of the I/O Subsystem 


Standards, channels are initialized to handle message passing between: 


two processes: the I/O Subsystem Manager and the appropriate 


Interface Handler. The tasks that are executed to initialize the 
channel, construct the message, and synchronize the message transfer 


are all performed transparently to the user. 


It is possible for the user himself to create and pass messages’ to a 
selected Interface Handler. However, to do this, the user must. 


identify the channel associated with the selected Interface Handler 


and construct the message according to the requirements of the 


Interface Handler. 


Information on the routines that implement interprocess communication 


via channels using native code run-time support is presented in the. 


Realtime Executive*s User*s Manual (MP373). Channel routines are 
documented for Microprocessor Pascal Executive users in the 
Microprocessor Pascal Executive User’s Manual. ” 


2.4.4 Interface Handler 


The Interface Handler provides the lowest level of interface with the 
actual physical device. The handler enables requests for logical 


services made in the user’~s code to be translated to requests’ for 


physical services on the actual device. 


By entering the I/O system at the File I/O Decoder or at the I/0 
Subsystem levels, the user need not be concerned with the requirements 
for accessing the Interface Handler. However, it is possible for the 


user to call the Interface Handler directly or invoke the Interface 


Handler via messages sent across channels as described in Subsection 
2.4.3. The user should refer to the user”s manual for the specific I/0 
Subsystem when directly accessing the Interface Handler. 
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Sep SECTION III 
FILE I/O DECODER ROUTINES 


3.1 GENERAL 


This section documents the entry points into the File I/O Decoder. The 
individual routines associated with these entry points are examined. 
atid: the parameters passed when each routine is accessed are defined. 
Pascal and assembly language calling sequences are presented for each... 
The- assembly language programmer must be familiar with the assembly. 
language programming standards and the conventions governing register. 
usage documented in the Realtime Executive User”’s Manual (MP373) to. 
understand the assembly language code and register usage. 


Prior to the description of these entry points, general information on 
user interface with the File I/O Decoder and parameter passing is 
presented. 


teed 7% 
we de 


3.2 USER INTERFACE WITH THE FILE I/0 DECODER 


As established previously, the user application interfaces with the 
File I/0 Decoder to perform device independent I/O on the target 
system. The means by which the user achieves this interface is 
described below for Pascal and assembly language users. | | 


e The Pascal User merely uses Pascal statements supported in 
the Microprocessor Pascal System to perform file 1/0 
operations. These Pascal statements, RESET, REWRITE, READ, 

| READLN, WRITE, and WRITELN, in turn invoke File I/0 
vs Decoder entry points invisibly to the user. Information on 
these Pascal statements is contained in the Microprocessor 
Pascal System User’s Manual (MP351). The Pascal user can 
also invoke the File I/O Decoder entry points directly as 
demonstrated in the calling sequences below. 


@e The assembly language user must invoke the File I/O 
in Decoder entry points directly in order to perform device 
- ° independent I/0. The assembly language calling sequences 
are presented below in Subsection 3.4. 


3.3 PARAMETER PASSING 


In order to understand the calling sequences presented below, the user 
should be aware of the conventions governing the way parameters are 
passed. These conventions apply to both Pascal and assembly. language 
users as decribed below. 





_" | @ When parameters are passed by reference, the address of ae 
ace the data required by, the called routine is passed. The “* 

: address is passed in one word. Parameters passed by “+" — 
reference can be changed by the called procedure. These “** 
Parameters include variables. te 


@e When parameters are passed by value, the actual data ~ 
required by the called routine is passed. This data can be 
Passed as one or two words (e.g., Long Integers are passed 
as two words). 2 


® Pointers are passed by value. However, the value passed is 
an address of some data (or data structure). 


@e Records and arrays are passed by reference (though the 
Pascal calling sequence may indicate that they are passed 
by value). In other words, the address of the record/array 
and not the data structure itself is passed to the called 

' procedure. 

Detailed information concerning parameter passing is presented in the 

Microprocessor Pascal System User”’s Manual (MP35l) for the Pascal user 

and the Realtime Executive User”’s Manual (MP373) for the assembly 

language user. , 


ea 


3.4 ‘FILE I/O DECODER ENTRY POINTS 


The File I/O Decoder entry points are discussed below in detail. 
Because of system conventions, the order in which several specifit 


routines may be invoked is fixed (e.g., the call to Connect must 


precede any other call to a file service, a file must be opened before 
accessed, etc.). This order is reflected in the descriptions below. “ 


In addition to the entry points presented here, other entry points are 
Present for internal use. As_ such, these entry points will not be | 
called by the user and are thus not documented below. | 


NOTE: In writing his code to access these various entry points, the 
user must be careful that the sharing of variables among processes is 
Synchronized (one method of achieving this synchronization is through: 
the use of semaphores). FIDs can be shared among processes within 
scope; however the restrictions of the specific I/O Subsystem invoked 
must be considered in any such attempt. 


3.4.1 System Initialization (DSINIT) 
Initialization of the File I/O Decoder and all I/O Subsystems with 
which it is linked occurs automatically at power-up time. The Ghost$ 


procedure present in the native code run-time support contains a call 
to the DSINIT routine in the File I/O Decoder. As a result of DSINIT 


3-2 














eo 
octe sb eB 4 


being accessed, each of the supported I/O Subsystems are entered at 
their respective initialization entry points. In this manner, system 
initialization takes place transparently to the user. 


In fact, invoking the DSINIT entry point leads to initiating the 
Gevices, characteristics tables, and configuration data associated 
with the File I/O Decoder and with each supported subsystem. Appendix 
‘B: presents pictures of the various data structures. Section VI 
describes how a system is configured. 


Pascal Calling Sequence: 
PROCEDURE DSINIT 
Assembly Language Calling Sequence: 


DATA CALLS 
DATA DSINIT 


3.4.2 Connecting the File to an I/O Subsystem (DSCONNECT) 


DSCONNECT must be the first file service requested and is called to 
connect a specified file pathname with the appropriate I/O Subsystem. 
At "CONNECT" time, the file decoder will invoke each subsystem 
supported on the target in succession until some subsystem recognizes 
the pathname parameter passed with the call. If no_ subsystem 
recognizes the pathname, an error condition is signaled (the naming 
conventions applicable to the file pathname are specific to the I/0 
Subsystem being invoked). When the file is recognized, internal data 
Structures are created and maintained to sustain the connection 
between the file and the physical node (or device). Also, the File 
Identifier (FID) is initialized. The FID connects the user with the 
associated I/O Subsystem enabling the user to perform subsequent file 
operations on the file. , 


NOTE: The Pascal user must do a type override to enable the pathname 
PROTneGE to point to a buffer of sufficient size to hold the pathname. 


After connect, legal file requests are DSCREATE, DSOPEN, DSDELETE, and 
DS§DISCONNECT. 


The Calling parameters for DSCONNECT are defined below. 
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Parameter > 


Pathname 
Pointer 


Number 
of Char- 
acters 


File | 
Identifier 


cath sme a ly pe nea a ee ek ake ORR ee, a a ee ee eh eer Ry sesh ee ee ee a ee 


Definition 


Pointer to buffer con- 


taining pathname of 
file to be serviced. 
This pathname is 

subsystem dependent. 


Number of characters 
contained in the 
pathname. 


Value returned by 
DSCONNECT enabling 
the I/O Subsystem to 
associate a specific 
File with a specific 
user. 


Pascal Calling Sequence: 


PROCEDURE DSCONNECT ( 


VAR My fid 


Pathname 
No_ of char 


Assembly Language Calling Sequence: 


Assume : 


MOV 
“MOV 
MOV 
A 
DATA 
DATA 


* 


@ 


The parameters for this 
following displacements 


local frame: 


Pathname Pointer 
Number of Characters 
My Fid 


LF ,*SP+ 
2(LF) ,*SP+ 


LF,*SP 


@ 


FOUR (CODE) ,*SP+ 


CALLS 
DSCONNECT 


Limits . Input/Output , 


Pointer: Input 
Word address. 
Buffer: - 

Character array ~ 
length of which 

depends on the 

subsystem. The 

pathname is left- 

justified in the 


buffer. 
Integer Input 
Integer Output 


DUMMY BUFFER_PTR; 
INTEGER; 
FID ); 


procedure are stored at the 
into the calling procedures 


at 0 
at 2 


at 4 


PASSING PATHNAME POINTER 


PASSING NUMBER OF CHARACTERS 
PASSING FILE IDENTIFIER 


where the following sequence is in the user’s prologue: 


MOD EQU 


DATA PRO-MOD 


$ 


MOD LABELS BEGINNING OF LOCAL DATA 


FOUR EQU S$-MOD 


PRO LABELS BEGINNING OF EXECUTABLE CODE 


ox 








. DATA 4 


3.4.3 DSCREATE 


we on 
oe i “eb 


The entry point DSCREATE creates a file by invoking the appropriate 
I/O Subsystem. The attributes of the file that is created are defined 
by the calling parameters passed to the DSCREATE command. The meaning 
of these attributes are discussed in detail in Appendix E. 


The parameterization for DSCREATE pertains to I/O Subsystems managing 

multifile devices. These parameters are ignored by I/O Subsystems not 

Supporting multifile devices. The Create function leaves the file in a- 
Closed condition so that the only legal operations are DSOPEN, 

DSDELETE, and DSDISCONNECT. 


The calling parameters passed to DS$CREATE are described below. 


Parameter Definition Limits Input/Output 
File Value returned by Integer Input 
Tdentifier DSCONNECT enabling 


the I/O Subsystem to 
associate a specific 
file with a specific 


user. 
_ Password Pointer to record struc- Pointer: Input 
“ . Gist ture containing Creator Word address; 
“ Pointer and User Passwords — Record Fields: 
creator Password: 
character array; 
User Password: 
character array. 
Protection Record defining access Read (Bits 0-3): Input 
Code protection. This record #1 thru #4; 
has four fields each Write (Bits 4-7): 
defining the level of #1 thru #4; 
access protection for Modify (Bits 8-11): 
a separate access activ- #1 thru #4; 
ity. These fields are: Exec. (Bits 12-15): 


Read, Write, Modify, and #1 thru #4. 
Bxecute. The levels of 
protection assigned are 

specified as #1 Any Ac- 

cess; #2 User Password; 

#3 Creator Password; and 

#4 No Access. See Appen- 

dix E for details. 


3-5 











File Type 


Logical 
‘Record 
Length 


Primary 
Allocation 


Secondary © 


Allocation 


A record containing four 
fields defining the 
physical and logical or- 
ganization of the file. 
These file attributes 
are discussed in Appen- 
dix E. 


File Type (Bits 
0-3): 

Contig.=l; 
Non-contig.= 2; 
Record Type (Bits 

4—7): 
Free Len.=l; 


Var. Len.=2; 
Fixed Len.=3; 
Usage (Bits 8-ll): 
Data File=l; 
Compression (Bits 
12-15): 
Uncompress.=l1; 
Compress.=2. 


Any positive 
integer. 


Length in bytes of the 
records contained in 

a file. For Fixed 

Length record files,. 

the actual record 

length is used. For 
Variable Length record 
files, the maximum length 
is used. For Free Region 
record files, a record 
length of 1 byte is used. 


Any non-negative 
Long Integer 
(two words). 


The minimum storage space 
(number of records) to be 
allocated to the file 
(represents maximum number 
in a contiguous file). 
Default is indicated by 
blank or zero. Free Length 
default = 800; Non-Free 
Length Default = 50. 


The increment (number of 
records) by which a non- 
contiguous file is allowed 
to grow per expansion (up 

to 16 expansion steps are 
allowed for non-contiguous 
files. Default is indicated 
by blank or zero. Default = 
Primary Allocation. 


Any non-negative 
Long Integer 
(two words). 


Pascal Calling Sequence: 
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~~ 


Input 


Input 


Input 


ri 


beg 


cf 
. 

















PROCEDURE DSCREATE ( My fid : FID; 
Pass code_list: PASSWORD LIST PTR; 
Protect : PROT: 
Er : FILE TYPE 
Log_rec_len : INTEGER; 
Pa_log_rec : LONGINT; 


Sa_log_rec LONGINT) ; © 


Assembly Language Calling Sequence: 


Assume: The parameters are stored at the following 
displacements into the calling procedure’s 
local frame (records are passed by address): 


My Fid at 0 
Passcode List Pointer at 2 
Protection Code at 4 
File Type at 6 
Logical Record Length at 8 
Primary Allocation at 10 
Secondary Allocation at 14 
MOV *LF ,*SP+ PASSING MY FID 
MOV @2 (LF) ,*SP+ PASSING PASS CODE LIST POINTER 
MOV LF, *SP PASSING ACCESS PROTECTION ADDRESS 
A @FOUR (CODE) ,*SP+ 
MOV LF,*SP PASSING FILE TYPE ADDRESS 
A @SIX (CODE) , *SP+ 
MOV @8 (LF) ,*SP+ PASSING LOGICAL RECORD LENGTH | 
MOV @10 (LF) ,*SP+ PASSING PRIMARY ALLOCATION (2 WORDS) 
MOV @12(LF) ,*SP+ 
MOV @14 (LF) ,*SP+ PASSING SECONDARY ALLOCATION (2 WORDS) 


MOV @16 (LF) ,*SP+ 
DATA CALLS 
DATA DSCREATE 


Where the following sequence appears in the user’s prologue: 


MOD EQU S MOD LABELS BEGINNING OF LOCAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


FOUR EQU S—-MOD 


DATA 4 
SIX EQU $-MOD 
DATA 6 


3.4.4 DSOPEN 


DSOPEN is called to prepare a file for reading, writing, or both 
depending on the access type specified by the Access Type parameter 





passed to this procedure. If the passwords passed to this command do | 
access type desired as 


not match 


the 


passwords 


required for 
identifed when the file was created, the Open will fail. If 
is successful, the type of of the file opened along with its number of | 


the 


the Open 


ond 


logical records and record length (if appropriate) are returned to the 


Type defined when the 
file was created is re- 
turned. 


word Address. 


user. Once DSOPEN has been called, all file services with the. 
exception of DSCONNECT, DSCREATE,. DSDELETE, and DSDISCONNECT are 
allowed until the file is closed. 
The parameters passed to the DSOPEN command are defined below. 
Parameter Definition Limits Input/Output 
File Value returned by Integer Input 
Identifier DSCONNECT enabling 
the I/O Subsystem 
to associate a specific 
file with a specific 
user. 
Password Pointer to an array Pointer: Input 
Pointer containing the Creator Word address; 
or User Password. Array: 
An array four 
characters in 
length. 
Access Indication of the type Byte Relative Input 
Type of access in which I/0 = l; 
is executed. Access type Sequential 
remains effective until = 2; 
the file is closed. Ac- Direct = 3. 
cess types are defined 
in Appendix E. 
Access Relationship between user Exclusion, Read, Input 
Privilege and the file which de- Write, Execute, 
fines the user’s activity and Extend: 
and precludes otner user False = 0; 
access. The user can True = l. 
specify True or False 
for each of five fields: 
Exclusion, Read, Write, 
Execute or Extend. For 
more information, see 
Appendix E. (Note: this 
record is packed to use 
bits 0,1,2,3, and 15 of 
the word.) 
File Type Record to which the File Pointer: Output 














Logical 
‘- Record 
~ “Length 


Number of 
Logical 
Records 


Integer to which the log- 
ical record length defined 
when file was created is 
returned. 


Integer to which number 

of logical records in the 
file is returned. In 

files of variable length 
records, an end of file re- 
cord is present and coun- 
ted as an extra record. 


Pascal Calling Sequence: 


PROCEDURE DSOPEN ( My fid 


Passwords 

Access _ type 

Access _ priv 
VAR Ft 


VAR Logical_rec_length 


VAR Number _log_rec 


Assembly Language Calling Sequence: 


Assume: 


MOV 
MOV > 
MOV 
MOV 
A 
MOV 
A 
MOV 
A 
MOV 
A 
DATA 
DATA 


Aes 
fe poe 
Lee 

Ses 
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Integer. Output 
Integer. Output 
FID 


PASSWORD PTR; 

FILE ACCESS MODE; 

FILE ACCESS PRIVILEGE; 
FILE TYPE; 

INTEGER; 

LONGINT) ; 


The parameters are stored at the following 
displacements into the calling procedures 
local frame (records passed by address): 


My Fid at 0 
Password Pointer at 2 
Access Type at 4 
Access Privilege at 6 
File Type at 8 
Logical Record Length at 10 
Number of Logical Records at 12 
*LF,*SP + PASSING MY FID 
@2 (LF) ,*SP+ PASSING PASSWORD POINTER 
@4 (LF) ,*SP+ PASSING ACCESS TYPE 
LF,*SP PASSING ACCESS PRIVILEGE ADDRESS 
@SIX (CODE) ,*SP + 
LF ,*SP PASSING FILE TYPE ADDRESS 
@EIGHT (CODE) ,*SP+ 
LF, *SP PASSING LOGICAL RECORD LENGTH ADDRESS . 
@TEN (CODE) , *SP+ 
LF ,*SP PASSING NUM. OF LOG RECORDS ADDRESS 
@TWELVE (CODE) ,*SP+ 
CALLS 
DSOFEN 


where the following sequence appears in the user’s prologue: 





MOD EQU $ MOD LABELS BEGINNING OF LOCAL DATA — 


DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 

SIX EQU $-MOD 
DATA 6 

EIGHT EQU S-MOD 
| DATA 8 
TEN EQU $-MOD 

DATA 10 
TWELVE EQU $-MOD 

DATA 12 


3.4.5 DSREAD : 


The call to DSREAD initiates a read operation on a file. The calling 


process begins the read and can (if appropriate) continue to execute 


without delaying until the read operation is complete. 


DSREAD provides for record organized data transfer. If the file is not 
Organized into logical records, the buffer will be filled in physical 
record length increments until no further physical record can be held. 
Data transfer begins at the current file position. At the end of the 
read operation, the file position is left pointing at the next 
available unit of data (record or byte, as appropriate). 


The variable Parameter Count is not set until I/O is complete. To be 


Sure that this parameter is set correctly, the user should call DSWAIT e 


after the call to DSREAD. 


The parameters passed to DSREAD are described below. 


Parameter Definition : Limits Input/Output 
File Value returned by Integer | Tnput 
Identifier DSCONNECT enabling 


the I/O Subsystem 
to associate a specific 
file with a specific 


user. 
Buffer Pointer to an array in Pointer: Input 
Pointer RAM into which the data Word Address 

read is transerred. Array: 


Ram-resident data 
area large enough 
to accomodate the 
number of bytes 
in the read. 


\ 

















Read Count Number of bytes to be Positive Integer Input 
read; input lesser of 
the number requested 
and the logical record 
length. 


Count Integer to which the Integer. Output 
actual number of bytes 
read is transferred. 


Pascal Calling Sequence: 


PROCEDURE D$READ ( My fid : FID; 
Buffer : DUMMY BUFFER PTR; 
Read_count > : INTEGER; 
VAR Count : INTEGER) ; 


Assembly Language Calling Sequence: 


Assume: The parameters are stored at the following 
| displacements into the calling procedure’s 
local frame (records are passed by address): 


Fid _ 4 at 0 

Buffer Pointer at 2 

Read Count at 4 

Count at 6 
MOV *LF,*SP+ PASSING FID 
MOV @2(LF) ,*SP+ PASSING BUFFER POINTER 
MOV @4 (LF) ,*SP+ PASSING READ COUNT 
MOV LF ,*SP PASSING COUNT 
A @SIX (CODE) ,*SP+ 


DATA CALLS 
DATA DSREAD 


where the following sequence advears in the user’s prologue: 


i 


MOD EQU $ MOD LABELS BEGINNING OF 7,0CAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


SIX EQU S—MOD 
DATA 6 


3.4.6 DSWRITE 


The call to DSWRITE initiates a write operation on a file. The calling 
process begins the write and can (if appropriate) continue to execute 
‘without delaying until the write operation is complete. | 


DSWRITE provides for record organized data transfer. If the file is 


- mot organized into logical records, the buffer will be filled in 











physical record length increments until no further physical record can 
be held. At the end of the write operation, the file is positioned to 
be ready to store the next unit of data (record or byte as 
appropriate). Type of access permited (byte-relative, sequential, or 
direct) is a function of the device itself and the access type for 
which the file was opened (see DSOPEN above). Access protection and 
Privilege are functions of the parameters passed to the DSCREATE and 
DSOPEN routines respectively. 





The parameters passed to DSWRITE are described below. 
Parameter Definition Limits Input/Output 


File . Value returned by Integer | Input 
Identifier DSCONNECT enabling 

the I/O Subsystem 

to associate a specific 

file with a specific 


user. 
Buffer Pointer to an array in Pointer: Input 
Pointer RAM from which data is Word Address 
to be transferred. Array: 
Ram-resident array 
size of which large 
enough to accomodate 
data transfer (as spe- 
cified in Write Count ON, 
below). a) 
Write Count The number of bytes Positive Integer Input 
to be written. 
Pascal Calling Sequence: 
PROCEDURE DSWRITE ( My fid FID; 


Buffer 
Write count 


DUMMY BUFFER_PTR; 
INTEGER) ; | 


Assembly Language Calling Sequence: 


Assume: The parameters are stored at the following 
displacements into the calling procedures 
local frame (records are passed by address): 








My Fid — at 0 | Aes 


Buffer Pointer at 2 

Write Count > at 4 
MOV *LF ,*SP+ PASSING MY FID 
MOV @2 (LF) , *SP+ PASSING BUFFER POINTER 
MOV @4 (LF) ,*SP+ PASSING WRITE COUNT 


DATA CALLS 
DATA DSWRITE 


3.4.7 DSRDWAIT 


DSRDWAIT is called to execute (as oppossed to initiate) a read 
operation. Unlike the action of DSREAD, the calling process begins the 
read and is then suspended until the read is completed. In other 
words, a call to DSRDWAIT results in the same action as a call to 
DSREAD followed by a call to DSWAIT. The parameterization of DSRDWAIT 
is the same as for DSREAD. , 


3.4.8 DSWRWAIT 


DSWRWAIT is called to execute (as oppossed to initiate) a write 
operation. Unlike the action of DSWRITE, the calling process begins 
the write and is then suspended until the write is completed. In other 


“words, a call to DSWRWAIT results in the same action as a call to 
\..- DSWRITE followed by a call to DSWAIT. The parameterization of DSWRWAIT 


is the same as for DSWRITE. 


3.4.9 DSPOSITION 


DSPOSITION is called to move the file position forward or backward 
prior to the next I/0 attempt. The Relative parameter specifies 
whether the change in file position will be relative to the current 
file position or absolute (relative to the start of the file). If this 
boolean parameter is passed as True, the Record parameter indicates 
the number of records by which the file position will change from the 
Current position (the sign of this value indicates whether movement is 
forward or backward). If Relative is passed as False, the Record 
Parameter specifies the absolute record number at which the file will 
be positioned. An error condition results if an attempt is made to 
position the file beyond the end of file mark = or prior to the 
beginning of file mark. Errors may also occur if the device does not 
Support record number. 


The parameters passed to DSPOSITION are described below. 


‘Parameter | Definition Limits Input/Output 


A File Value returned by Integer — Input 
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Identifier DSCONNECT enabling | | 
the I/O Subsystem : | 
to associate a specific 
file with a specific 





user. 
Relative Boolean parameter by False = 0; . Input 
which.user specifies if True =1l. 


repositioning of file 
will take place in re- 
lation to current file 
position (true) or ab- 
solute. See explana- 
tion above. 


Record Depending on value of Long Integer | Input 
Number Relative parameter, the (two words) 

number of records the 

file will be moved from 

the current position, or 

the record number at 

which the file will be 

newly positioned. See 

explanation above. 


Pascal Calling Sequence: 
PROCEDURE DSPOSITION ( My fid 


Relative 
Record No. 


FID; 
BOOLEAN ; Sas 
LONGINT) ; ae. 


7 Assembly Language Calling Sequence: 


Assume: The parameters are stored at the following 
displacements into the calling procedure’s 


local frame (records are passed by address): 


My fid at 0 | 
Relative at 2 | 
Record No. at 4 














MOV *LF,*SP+ PASSING MY FID 


MOV @2 (LF) ,*SP+ PASSING RELATIVE 
MOV @4(LF) ,*SP+ | PASSING FIRST WORD OF RECORD NO. 


MOV @6 (LF) , *SP+ PASSING SECOND WORD OF RECORD NO. 
DATA CALLS : : 
DATA DSPOSI 


3.4.10 DSWAIT 


By calling DSWAIT, a user requires the process to wait for the 
completion of the I/O service he previously initiated for that file 
(FID). Regardless, a wait will automatically occur on a user’s 
initiate I/O request if he has a current request outstanding on that 
— file (FID). The calling parameters passed to DSWAIT are described 
elow. 


Parameter Definition Limits Input/Output 


File Value returned by Integer Input 
Identifier DSCONNECT enabling : 

the I/O Subsystem to 

associate a specific 

file with a specific 

user. 


Pascal Calling Sequence: 
PROCEDURE DSWAIT ( My fid : FID); 
Assembly Language Calling Sequence: 

Assume: The parameters are stored at the following 
displacements into the calling procedure’s 
local frame (records are passed by address): 
FID _ at 0 | 

MOV *LF,*SP+ PASSING FID 


DATA CALLS 
DATA DSWAIT 


3.4.11 DSSTATUS 


The function DSSTATUS can be called once a file has been CONNECTED to 
check on the current status (success or failure) of the user”s oldest 
Outstanding request ona file (the oldest request on the FID). In the 
File Identifier Record itself (see Appendix B for illustration), a 


- Status field is present to capture status information. This function 


enables the user to inspect this information. Appendix C details the 
various status messages and provides some suggestions for corrective 
actions when appropriate. 
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Parameter Definition Limits Input/Output | 


eee al 


File Value returned by Integer Input 
Identifier DSCONNECT enabling | | 
I/O Subsystem to 
associate a specific 
file with a specific 
user. 


- Pascal Calling Sequence: 


FUNCTION DS$STATUS (My Fid : FID) : INTEGER; 
Assembly Language Calling Sequence: 
Assume: The parameters are stored at the | 


following displacements in the 
Calling procedure’s local frame. 


My Fid | at 0 
Result will be saved at 2 
MOV *LF, *SP+ PASSING FID 
DATA CALLS 
DATA DSSTAT 
MOV *SP,@2 (LF) SAVING RESULT 


3.4.12 DSDSTATUS 


DSDSTATUS enables the user to examine status information on the 1/0 
Subsystem level (compare'to DSSTATUS which returns a status message at 
the FID level). Because the meanings of the status messages returned 
by DSDSTATUS are I/O Subsystem dependent, the user must refer to the 
user“°s manual dedicated to the specific I/O Subsystem for message 
definitions and corrective actions. The only parameter passed to 
DSDSTATUS is the FID. 


Parameter Definition Limits Input/Output 
File Value returned by Integer Input 
Identifier DSCONNECT enabling the 


I/O Subsystem to asso- 

Ciate a specific file 

with a specific user. 
Pascal Calling Sequence: 


FUNCTION DSDSTATUS (My Fid : FID): INTEGER 


Assembly Language Calling Sequence: 
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Assume: The parameters are stored at the 
following displacements in the 
Calling procedure’s local frame. 


My Fid at 0 
Result will be saved at 2 
MOV *LF, *SP+ PASSING FID 
DATA CALLS 
DATA DSDSTA 
MOV *SP,@2 (LF) SAVING RESULT 


3.4.13 DSVALID 


DSVALID is a Boolean function that may be called to check for valid 
state transitions for the FID. State refers to the FID condition such 
as Connected, Created, Open for Access, etc (refer to Appendix C for 
information regarding valid state changes). The parameters passed to 
DSVALID are defined below. 


Parameter Definition Limits Input/Output 


File Value returned by Integer - Input 


ry Identifier DSCONNECT enabling 


the I/O Subsystem 
to associate a 
specific file with 
a specific user. 


Opcode Operation attempted on Scheck = 
the FID. Sopen = l 
| 7 


H Input 


it 
Ui 
=e 


S$disconnec 
Screate = 
Sdelete = 
Sposition 


il ~] OV cr se we 
me =O 


Lee) 
@ 


Pascal Calling Sequence: 


FUNCTION DSVALID( My fid : FID; 
Op : FID OPERATION) : BOOLEAN; 


Assembly Language Calling Sequence: 
Assume: The parameters are stored at the following 


displacements into the calling procedure’s 
local frame (records are passed by address): 
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MOV 
MOV 
DATA 
DATA 
MOV 


My Fid at 0 


Fid Operation . at 2 

Result will be saved at 4 

* LF ,*SP+ PASSING FID POINTER 
@2(LF) , *SP+ PASSING FID OPERATION 
CALLS | | 

DSVALI 

*SP,@4(LF) SAVING RESULT 


3.4.14 DSABORTIO 


DSABORTIO 


is 


called to abort all outstanding read/write operations a 


user has requested on a file (i.e, all outstanding read/write requests 
on a FID). The only parameter passed to DSABORTIO is the FID. 


Parameter 


File 
Identifier 


Definition Limits 


Value returned by Integer. 
DSCONNECT enabling 

the I/O Subsystem 

to associate a 

specific file with a 

specific user. 


Pascal Calling Sequence: 


PROCEDURE DSABORTIO (My fid : FID); 


Assembly Language Calling Sequence: 


Assume: 


MOV 
DATA 
DATA 


The parameters are stored at the following 
displacements into the calling procedures 


local frame (records are passed by address): 


My Fid at 0 
*LF ,*SP+ PASSING MY FID 
CALLS 

DSABOR 


3.4.15 DSCLOSE 


Input/Output © 


Input 


DSCLOSE is accessed to enable the user to close the file (FID) when no 
more outstanding I/O requests are present. The Close EOF parameter (a 
BOOLEAN parameter) enables the file to be closed with the End-of-File 
mark being placed at. the current file position (if response is True). 
(False), the End-of-File mark is left unchanged (i.e., the 


Otherwise 
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last record in the file remains the same). The user who closes with 
End of File must be careful to avoid inadvertently placing an EOF 
prior to the last record. This is especially true if the user had 
written to the file using random access. The user who had opened a 
file for reading only should always close without EOF to avoid an 
error. 


After a call to DSCLOSE, the only valid file requests are DSOPEN, 
DSDELETE, or DSDISCONNECT. 


The parameters passed to DSCLOSE are described below. 


Parameter Definition | : Limits Input/Output 


File Value returned by Integer Input 
Identifier DSCONNECT enabling 
| the I/O Subsystem 

to associate a 

specific file with 

a specific user. 


Close End BOOLEAN parameter by False = 0 
of File which user specifies True = 1 
whether he wishes to 

close with EOF. A 
true response means 
that an EOF mark 
Should follow the 

last record accessed. 
False indicates that 
EOF remains unchanged. 


; Input — 


Pascal Calling Sequence: 


PROCEDURE DSCLOSE ( My fid : FID; | 
Close With_EOF : BOOLEAN ); 


Assembly Language Calling Sequence: 
Assume: The parameters are stored at the following 


displacements into the calling procedure’s 
local frame (records are passed by address): 


My Fid | at 0 
Close With EOF at 2 
MOV *LF,*SP+ PASSING FID 


MOV @2(LF) ,*SP+ PASSING CLOSE WITH EOF 
DATA CALLS oe 
DATA DSCLOSE 
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3.4.16 DSDELETE 


DSDELETE is called to delete a file that has been closed for 
except for 


thus 


preventing 


all further 


requests 


access, 
DSDISCONNECT or 


DSCREATE. The calling parameters passed to DSDELETE are defined below. 


Parameter 


File 
Identifier 


Password 
Pointer 


Definition 


Value returned by 
DSCONNECT enabling 

the I/O Subsystem 

to associate a specific 
file with a specific 
user. 


Pointer to a data struc- 
ture containing the crea- 
tor or user password. 
Required password speci- 
fied in Modify field of 
Protection record defined 
when file was created. 


Limits Input/Output 
Integer Input 
Pointer: Input 


Word Address. 
Passwords: 
Character arrays, 
each four charac- 
ters in length 
(either Creator 








or User). 
Pascal Calling Sequence: 


PROCEDURE DSDELETE ( My Fid 


: FID; 
Pass : 


PW PTR); 


Assembly Language Calling Sequence: 


Assume: The parameters are stored at the following 
displacements into the calling procedure’s 
local frame (records are passed by address): 

My Fid at 0 
Password Pointer at 2 

MOV *LF,*SP+ PASSING FID 

MOV @2(LF) ,*SP+ PASSING PASSING POINTER 

DATA CALLS 

DATA DSDELE 


3.4.17 DSDISCONNECT 


The last operation performed on the file (FID) by a user is 
DSDISCONNECT. The call to DSDISCONNECT severs the connection between 
the file and the physical node (or device) on the target. As a_ result 
of this procedure, the memory allocated to hold the File Identifier 


Record (FID) is returned to the heap. 
File Identifier is 


The only parameter passed to DSDISCONNECT, the 


passed by address on input. 
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Parameter Definition . Limits | Input/Output 


File Value returned by Integer Input 
Identifier DSCONNECT enabling 

the I/O Subsystem to 

file with a specific 

user. 


Pascal Calling Sequence: 

PROCEDURE DSDISCONNECT (VAR My fid : FID); 
Assembly Language Calling Sequence: 

MOV *LF,*SP+ PASSING FID 

DATA CALLS 

DATA DSDISC 


3.4.18 DSTERM 


At process termination, the user may call DSTERM to deallocate memory 
resources holding the remaining file data structures (including all 


_-FIDS currently outstanding). DSTERM provides the means to terminate 


all user connections with I/O Subsystems using one line of code. Thus, 
the call to DSTERM makes calls to DSDISCONNECT for individual 
subsystems unnecessary. DSTERM has no calling parameters. 
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SECTION IV 


THE INTERPROCESS COMMUNICATION SUBSYSTEM 


4.1 GENERAL 


This section of the manual presents a specific I/O Subsystem, the 
Interprocess Communication (IPC) Subsystem. This subsystem is supplied 
to the Pascal user in the Microprocessor Pascal Executive (MPX) and 
provided for the assembly language user in the Device Independent File 
I/O Package. The purpose of this subsystem is to implement file-level 
communication between processes within a 9900 target system. This is 
accomplished by passing data from process to process via channels 
using in-memory buffers. 


Interprocess Communication (IPC) Subsystem routines can be invoked via 
the File I/O Decoder or directly by the user. Subsection 4.3 below 
describes the former mode: Subsection 4.4 the latter. 


Interface with the IPC Subsystem is consistent with the standards 
governing interface with all other I/O Subsystems (as described in 
this manual) that may be accessed by the File I/O Decoder. This is 
true even though the IPC Subsystem is concerned with processes and not 
devices. 


‘ 4,2 IMPLEMENTATION OF THE IPC SUBSYSTEM 


Before describing the methods of invoking the IPC Subsystem, it is 
necessary to discuss its implementation. 


I/O between processes is managed through files. An IPC file may be 
thought of as a path of information between processes. A port can be 
viewed as providing a sending and receiving process with access to the 
path. Each process can be viewed as a node. Ports are defined for 
input and output by the invocation of special IPC routines. 


Information is passed over the path in the form of messages (the 
structure of messages along with other IPC data structures are 
presented in Appendix B) 


A file (comprising a message path) is implemented by a data structure 
called the Pathname .Record The Pathname Record contains data 
Structures required to synchronize and control the message flow 
between processes. Message flow is actually implemented over channels 
The Channel Record is used to implement channels. ‘Both the Pathname 
Record and the Channel Record are system global data structures. 


Ports are implemented by the File Identifier (FID), the File Variable 
Record, and the Message Record. The latter data structures are local 
to the user’s implementation of the IPC I/O Subsystem. The IPC data 


. $tructures are illustrated and described in Appendix B. 


4—] 


4.3 IPC ACCESS VIA THE FILE I/O DECODER 


Like other I/O Subsystems, the IPC Subsystem has a general set of 
entry points corresponding to the file service entry points present in 
the File I/O Decoder (File I/0 Decoder entry points have been 
described in detail in Section III of this manual). By way of these 
I/O Subsystem entry points, the device independent file services 
requested in the File I/O Decoder are translated into service requests 
of the IPC Subsystem. When accessing the IPC Subsystem in this way, 
the user is oblivious of its entry points and their calling sequences. 
I/O Subsystem initalization takes place via the File I/O Decoder entry 
point for initialization and all access to IPC is transparent to the 
user. 


4.4 DIRECT USER ACCESS OF IPC SUBSYSTEM ENTRY POINTS 


The paragraphs that follow describe how Pascal and assembly language 


users may directly access the entry points into the IPC Subsystem. 
Each entry point definiton is presented in terms of its meaning within 
this particular I/O Subsystem. However, the entry points into this I/O 
Subsystem are general to all I/O Subsystems. Thus, the parameter 
definitons and calling sequences presented below have ae general 
relevance to all I/O Subsystems. 


For the definitions of the file service routines (accessed via the 
File I/O Decoder) corresponding to these I/O Subsystem entry points, .. 


refer to Section III of this manual. 


The entry point names for this subsystem are formed by adding the 
prefix "IPCS$" to the generic name of the file serivce (connect, open, 
read, etc.). The rules and conventions governing parameter passing in 
the calling sequences presented below are the same as those described 
in Subsection 3.l. 


4.4.1 IPCSINIT 


IPCSINIT is called to initialize the data structures used within the 
IPC Subsystem and set up synchronization and system access to all 
files. This routine initializes a mutual exclusion guard for the list 
of all pathnames connected to the IPC Subsystem and links’ the 


Subsystem r2cord (see below) with the list of all subsystem records. 


IPCSINIT must be called once prior to the calling of any other IPC 
routines. | : 


The parameters passed to IPCSINIT are defined below. . 


Parameter 


Service 
Directory 


Port 
Constants 
Record 
Pointer 


Subsystem 
Record 


Definition Limits | Input/Output 


Pointer to the Service Integer. Input 
Directory for the IPC (Additional detail 
Subsystem. can be found fol- 


lowing the calling 
sequences.) 


Pointer to the Port Ignored by this © Tgnored 
Constants Record. Not subsystem. 
used by this subsystem. 


é 


Pointer to Subsystem Integer. Output 
related data structures. 

This pointer must be 

supplied in each call to 

the IPC CONNECT routine. 


Pascal Calling Sequence: 


PROCEDURE IPCSINIT( Service 


: Service directory ptr; 
Port cons : Port_constants ptr; 
VAR Subsys : Subsystem ptr) ; 


Assembly Language Calling Sequence: 


Assume: 


MOV 
MOV 


MOV 
A 


DATA 
DATA 


The parameters for this procedure are stored at the 
following displacements into the calling procedure’s 
local frame: 


Service directory Pointer at 0 
Port Constants Pointer at 2 
Subsystem Record Pointer at 4 


*LF,*SP+ PASSING SERVICE DIRECTORY POINTER 
@2(LF) ,*SP+ PASSING PORT CONSTANTS RECORD POINTER 
LF,*SP PASSING SUBSYSTEM RECORD POINTER 
@FOUR(CODE) ,*SP+ 

CALLS 

IPCSIN 


where the following sequence appears in the user’s code: 








MOD EQU $ MOD LABLES BEGINNING OF LOCAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


FOUR EQU S$—-MOD 
DATA 4 


Service Directory, the data structure passed as the first parameter to 
this procedure, is supplied in the IPC Subsystem. The Pascal user can 
declare the procedure containing this directory (IPCSSD) as EXTERNAL 
and pass IPCSSD“s location as the Service Directory parameter. This is 
accomplished by making Service Directory an Integer via a type 
override and setting the parameter Service Directory to the location 
of IPCSSD: 


SERVICE: : INTEGER := LOCATION (IPCSSD) | 
The assembly language programmer REF*s IPCSSD and sets the Service 
Directory to the location of IPCSSD using a DATA instruction. 
4.4.2 IPCSCONNECT 
IPCSCONNECT searches the list of all pathnames connected to the IPC 


Subsystem to determine if there is a path corresponding to the input 
Parameter Pathname (this parameter is passed by address even though 


this is not indicated in the Pascal calling sequence). If not, a path — 


is constructed by allocating a pathname record and associated message 
channel. 


NOTE: IPC accepts any pathname. Since the I/O decoder presents 
pathnames to I/O subsystems for connection in the order in which the 
subsystems are enumerated in the I/O subsystem directory present in 
CONFIG, the entry for IPC must be last if other subsystems are to have 
a chance to accept the pathname. 


Once a pathname record is obtained, IPCSCONNECT creates local data | 


structures defining a path and returns the identifier of the 


associated file as the FID parameter which must be used to make 


subsequent I/O service requests. 


The parameters passed to IPCSCONNECT are described below. 


Parameter Definition Limits : Input/Output 
Subsystem Pointer to Subsystem Integer. Input 
Record related data structures. : 


This pointer is supplied 
by the IPCSINIT routine. 











_- Pathname Memory data structure 

: holding file pathname 

specifying name of path 
over which messages will 


be sent. 
Length Character length of the 
| above pathname. 
File Value returned by IPCS- 


Identifier CONNECT enabling the 

| | IPC Subsystem to relate 
a specific file toa 
specific user. 


Pascal Calling Sequence: 
PROCEDURE IPCSCONNECT ( Sub 
| VAR Pathname 
Length 
VAR F | 


Assembly Language Calling Sequence: 


Character array Input 
large enough to 

accomodate path- 

name being passed. 

(Pascal user will 

need to do a type 
override.) 


Integer. Input 


Integer. Output. 


SUBSYSTEM PTR; 
DUMMY BUFFER; 
INTEGER; 

FID ); 


Assume: The parameters for this procedure are stored at the 
following displacements into the calling procedure’s 


local frame: 


Subsystem Record Pointer at 0 


Pathname Address at 2 
Length at 4 
FID : at 6 
MOV * LF ,*SP+ PASSING SUBSYSTEM RECORD POINTER 
MOV LF ,*SP PASSING PATHNAME ADDRESS 
INCT *SP+ | | 
MOV @4 (LF) ,*SP+ PASSING LENGTH 
MOV LF ,*SP PASSING FID VARIABLE 
A @SIX (CODE) ,*SP+ 


DATA CALLS 
DATA IPCSCO 


where the following sequence appears in the user’s code: 


MOD EQU $ MOD LABLES BEGINNING OF LOCAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


SIX EQU $-MOD 
DATA 6 








4.4.3 


Routine 


IPCSCREATE 


order to define the characteristics of that path. 


The parameters File Type and Logical Record Length (see below) 
characteristics of 
Password, Protect, Primary Allocation, and Secondary Allocation 


the file serving 


as the 


define 


path. The parameters 


are 


included for compatibility with the "Create" service routines of other 
I/O subsystems but are ignored by the IPC Subsystem. 


The parameters passed to IPCSCREATE are 


Parameter 


File 
Identifier 


Password 
Pointer 


Protection 
Code 


File Type 


Logical 
Record 
Length 


Primary 
Allocation 


Definition 


Value returned by IPCS$- 
CONNECT enabling the 
IPC Subsystem to relate 
a specific file toa 
specific user. 


Pointer to record struc- 
ture containing Creator 
and User Passwords. 


Record defining access . 
protection. 


A record containing four 
fields defining the 
physical and logical or- 
ganization of the file. 
These file attributes 
are discussed in Appen- 
dix E. 


The actual (fixed length) 
Or maximum allowable 
(variable length) byte 
length of the records in 
the file. 


Minimum storage sPace 
in the file. 


defined below. 


Limits 


Integer. 


Ignored by 
subsystem. 


Ignored by 
subsystem. 


File Type 
0-3): 


this 


this 


(Bits 


Contig.=l; 
Non-contig.= 2; 
Record Type (Bits 


4-7): 


Free Len.=l; 


Var. 


Len.=2; 


Fixed Len.=3; 


Usage (Bits 8-11): 


Data File=l1; 
Compression (Bits 


12-15) : 


Uncompress.=l; 
Compress.=2. 


Any positive 


integer. 


This two-word 
parameter is 


ignored. 


Input/Output 


Input 


Ignored 


Ignored 


Input 


Input 


Ignored 


IPCSCREATE must be called by a process connected to. a path in ee 


may 


on 














Secondary Incremental storage . This two-word Ignored 
Allocation space in the file. - parameter is 


ignored. 


' Pascal Calling Sequence: 


PROCEDURE IPCSCREATE ( My fid > FID; 
Pass_code_ list : PASSWORD _LIST POINTER; 
Protect : PROT; 
Ft | : FILE TYPE; 
Log_rec_len : INTEGER; 
Pa_log rec : LONGINT; 


Sa_log rec LONGINT) ; 


Assembly Language Calling Sequence: 


Assume: The parameters are stored at the following : 


displacements into the calling procedures 
local frame (records are passed by address): 


My Fid 3 at 0 
Passcode List Pointer at 2 
Protection Code at 4 
File Type at 6 
Logical Record Length at 8 
Primary Allocation at 10 
Secondary Allocation at 14 
MOV *LF ,*SP+ PASSING FID 
CLR *SP+ ‘PASS CODE PARAMETER IGNORED 
CLR *SP+ ACCESS PROTECTION PARAMETER IGNORED 
MOV LF,*SP PASSING FILE TYPE ADDRESS 
A @SIX (CODE) ,*SP+ 
MOV Q8 (LF) ,*SP+ PASSING LOGICAL RECORD LENGTH 
MOV @10 (LF) ,*SP+ PASSING PRIMARY ALLOCATION (2 WORDS) 
MOV @12(LF) ,*SP+ 
MOV @14 (LF) ,*SP+ PASSING SECONDARY ALLOCATION (2 WORDS) 


MOV @16 (LF) ,*SP+ 
DATA CALLS | 
DATA IPCSCR 


Where the following sequence appears in the prologue of the application 


MOD 


SIX 


EQU S MOD LABELS BEGINNING OF LOCAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


EQU S-MOD 
DATA 6 
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4.4.4 IPCSOPEN 


After the characteristics of a path have been defined, each process 
that is connected to the path must call IPCSOPEN to open the port for 
communication. 


The Privilege parameter specifies whether the port will be a producer 
(writer) or a consumer (reader). Note that a port cannot be both. The 
Password and Access Type parameters are not used by the IPC Subsystem. 
The parameters File Type and Logical Record Length are returned with 


the values that were specified when IPCSCREATE was called. The number 
of Records parameter is set to 0. 


Logical 
Records 


Definition 


the number of logical 
records is returned. 
This number is always 
zero. 


— 


Parameter Limits | Input/Output 
File Value returned by IPCS- Integer. Input 
Identifier CONNECT enabling the 
IPC Subsystem to relate 
a specific file to a 
specific user. 
Password Pointer to an array con- Ignored by this Ignored 
Pointer taining Creator or User subsystem. 
Password. 
Access Indication of the type Ignored by this Ignored 
Type of access by which I/0 subsystem. . 
3 is performed. 7 
Access This parameter defines Read Access (Bit l): Input 
Privilege whether port will be False = 0; 
used for input or out- True = l; 
put. Port cannot be Write Access (Bit 2): 
used for both. False = 0; 
True = l; 
Execute Access 
(Bit 3): 
Must be False. 
File Type Variable to which File Defined above Output. 
| Type record, defined IPCSCREATE. 
when file was created, | 
is returned. 
Logical Integer to which Log- Integer. Output 
Record ical Record Length, 
Length defined when file was 
created, is returned. 
Number of Long Integer to which Long Integer. 


Output 








Pascal Calling Sequence: 


PROCEDURE IPCSOPEN ( 


VAR 
VAR 
VAR 


Assembly Language Calling 


Assume: 


MOV 
CLR 
CLR 
MOV 
A 

MOV 
A 

MOV 
A 

MOV 


OA 


DATA 
CALL 


My Fid 
Password Pointer 
Access Type 
Access Privilege 

File Type 

Logical Record Length 
Number of Logical Records 


*LF,*SP + 


*SP+ 
*SP+ 


LF,*SP 


My fid 

Password 

Access type 

Access priv. 

FT 

Logical rec_length 
Number log rec 


Sequence: 


at 
at 
at 
at 
at 


at 
at 


FID; 

PASSWORD PTR; 

FILE ACCESS MODE; 

FILE ACCESS _ PRIVILEGE; 
FILE TYPE; 

INTEGER; 

LONGINT) ; 


The parameters are stored at the following 
displacements into the calling procedure’s 
local frame (records passed by address): 


rr ON kN © 


NI © 


PASSING FID 

PASSWORD POINTER IS IGNORED 
ACCESS TYPE PARAMETER IS IGNORED 
PASSING ACCESS PRIVILEGE ADDRESS 


@SIX (CODE) ,*SP + 


LF,*SP 


PASSING FILE TYPE ADDRESS 


@EIGHT (CODE) ,*SP+ 


LF,*SP 


PASSING LOGICAL RECORD LENGTH ADDRESS 


@TEN (CODE) ,*SP+ 


LF,*SP 


PASSING NUM. OF LOG RECORDS ADDRESS 


@TWELVE (CODE) ,*SP+ 


CALLS 


IPCSOP 


where the following sequence appears in the user’s code: 


MOD 


SIX 


BIGHT 


TEN 


" . TWELVE 


EQU 


DATA PRO-MOD 


EQU 
DATA 
EQU 
DATA 
EQU 
DATA 
EQU 
DATA 


$ 


S-—MOD 
6 
$-MOD 
8 
S-MOD 
10 
S-MOD 
12 


MOD LABELS BEGINNING OF LOCAL DATA 
PRO LABELS BEGINNING OF EXECUTABLE CODE 








4.4.5 IPCSWRITE 





Following the call to IPCSOPEN, a process can begin transmitting or 
receiving data from the file depending upon its I/O mode. If a process 
Opens a file as a writer, it can transmit data to the file by calling 
IPCSWRITE. 


NOTE: The Pascal user can doa type override to enable the buffer 
pointer to point to a buffer of sufficent size to accomodate the data 
transfer. 


The parameters passed to IPCSWRITE are defined below. 


Parameter Definition Limits Input/Output 
File Value returned by IPCS- Integer. Output 
Identifier CONNECT enabling the 


IPC Subsystem to relate 
a specific file to a | 
Specific user. 


Buffer Pointer to a character Pointer: Input 
Pointer array in RAM from which Word Address 
data is written. Array: 


Ram-resident data 
area containing data 


end 


for transfer. S 
Write Count The number of bytes Positive Integer Input 
3 to be written. 
Pascal Calling Sequence: 
PROCEDURE IPCSWRITE ( My fid FID; 


Buffer — 


DUMMY BUFFER_PTR; 
Write count 


INTEGER) ; 


Assembly Language Calling Sequence: 


Assume: The parameters are stored at the following 
- displacements into the calling procedure’s 
local frame (records are passed by address): 





My Fid | at 


0 
Buffer Pointer -at 2 
Write Count at 4 
MOV *LF,*SP+ PASSING FID 
MOV Q@2(LF) ,*SP+ | PASSING BUFFER POINTER 
MOV @4 (LF) ,*SP+ PASSING WRITE COUNT 


DATA CALLS 
DATA IPCSWR 


4.4.6 IPCSREAD 


If a process opens a file as a reader, it can receive data from the 
file by calling IPCSREAD. 


The count parameter (below) is not set until I/O is complete. To be 
sure that this parameter is set correctly, the user should call 
IPCSWAIT after the call to IPCSREAD. The parameters passed to IPCSREAD 
are defined below. 


Parameter Definition Limits Input/Output 
File Value returned by IPCS- Integer. | Input 
Identifier CONNECT enabling the 


IPC Subsystem to relate 
a specific file toa 
specific user. 


Buffer Pointer to a character Pointer: Input 
Pointer array in RAM into which Word Address 

the data read is trans- Array: 

ferred. Ram-resident data 


area large enough 
to accomodate the 
number of characters 


read. 
Read Count Number of bytes to be Positive Integer Input 
read. 
Count Number of bytes that Positive Integer Output 
were actually transfer- , 
red. 
Pascal Calling Sequence: 
PROCEDURE IPCSREAD ( My Fid : FID; 
Buffer : DUMMY _BUFFER_PTR; 
Read_ count : INTEGER; 
VAR Count ¢ INTEGER) ; 

















Assembly Language Calling Sequence: 





Assume: The parameters are stored at the following 
displacements into the calling procedures 
local frame (records are passed by address): 


My Fid © | at 0 | | 





Buffer Pointer | at 2 | 
Read Count at 4 ! 
Count at 6 | 
MOV *LF,*SP+ PASSING FID 
MOV @2(LF),*SP+ PASSING BUFFER POINTER : 
MOV @4(LF) ,*SP+ PASSING READ COUNT 
MOV LF,*SP PASSING COUNT 
A @SIX (CODE) , *SP+ 


DATA CALLS | | 
DATA IPCSRE 


where the following sequence appears in the users code: 


MOD EQU $ i MOD LABELS BEGINNING OF LOCAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


SIX EQU S-MOD | — | 
DATA 6 | eet : 


4.4.7 IPCSWAIT 


Following a call to either IPCSREAD or IPCSWRITE, a process’ should 
call IPCSWAIT. This routine will wait for the completion of all 
Outstanding requests on the specified FID. Until this routine has been 
called, a process cannot be sure that all of the data has been . 
transmitted or received. | 


The parameters passed to IPCSWAIT are defined below. 


Parameter Definition Limits Input/Output 
File Value returned by IPCS- Integer. Input 
Identifier CONNECT enabling the | 


IPC Subsystem to relate 
a specific file to a 
Specific user. 
Pascal Calling Sequence: 
PROCEDURE I: ‘WAIT ( dy _fid : FID); 


Assembly Language Calling Sequence: | aA 
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Pu 
+ ‘ 
Toe ly 


Assume: The parameters are stored at the following 
| displacements into the calling procedures 
local frame: 


My Fid at 0 


MOV *LF,*SP+ | PASSING FID 
DATA CALLS 
DATA IPCSWA 


4.4.8 IPCSCLOSE 


Once all data has been written or no more data is to be read from a 
file, IPCSCLOSE should be called to mark the file as having stopped 
data communication. IPCSCLOSE shuts down a port without disassociating 
it from the path to which it is connected. The parameter Close With 
EOF (see below) is not used by the IPC Subsystem. If a port is closed, 
it may be reopened with the same or different I/O characteristics (see 
IPCSOPEN above). : 


The parameters passed to IPCSCLOSE are defined below. 











Parameter Definition Limits Input/Output 


File Value returned by IPCS- Integer. Input 
Identifier CONNECT enabling the 

IPC Subsystem to relate 

a specific file to a 

specific user. 


Close With Boolean parameter Ignored by this Ignored 
End of File by which user speci- subsystem. 
. fies whether or not 
he wishes to close 
with the same end 
of file. 


Pascal Calling Sequence: 


PROCEDURE IPCSCLOSE ( My fid 


a FID; 
Close With_EOF 


BOOLEAN) : | 


Assembly Language Calling Sequence: 
Assume: The parameters are stored at the following 


displacements into the calling procedures 
local frame (records are passed by address): 
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My Fid ; at 0 


Close With EOF at 2 
MOV *LF ,*SP+ PASSING FID 
CLR *GP+ | CLOSE WITH EOF PARAMETER IGNORED 


DATA CALLS 
DATA IPCSCL 


4.4.9 IPCSDISCONNECT 


When a process no longer needs access to a particular path (and the 
associated file is closed), IPCSDISCONNECT should be called to 
deallocate the data structures associated with the file and disconnect 
the process from the path. If no more processes remain connected to 


the path, the data structures associated with the path will also be 


deallocated. 


The only parameter passed to IPCSDISCONNECT is the FID passed by 
address on input. 


Parameter Definition | Limits Input/Output 
File Value returned by IPCS- Integer Input 
Identifier CONNECT enabling the (set to nil 

IPC Subsystem to relate On return to 


a specific file toa callér). 
specific user. 


PROCEDURE IPCSDISCONNECT ( VAR My Fid : FID ); 
Assembly Language Calling Sequence: 

Assume: The parameters are stored at the following 
displacements into the calling procedure’s 
local frame: 

My Fid | at 0 
MOV *LF,*SP+ PASSING FID 
DATA CALLS 
DATA IPCSDI 
4.5 IPC SYNCHRONIZATION 


This subsection details special interactions among processes calling 
certain IPC routines. 











4.5.1 IPCSCREATE/IPCSOPEN Interaction 


A path for communicating among processes is established by the first 
process to call IPCSCONNECT with a given pathname. Each process must 
call IPCSOPEN to begin communicating over the path. All processes 
Calling IPCSOPEN for a path are suspended until some process calls 
IPCSCREATE to specify the characteristics of the path; all calls to 
IPCSCREATE for a pathname that already exists will be ignored. 7 


4.5.2 IPCSOPEN/IPCSCLOSE Interaction 


Before a file (FID) can be reopened, it must be closed. Following a 
close operation on a file, it can be reopened in either read or write 
mode. It is possible for a process to read or write from a file, close 
the file, and reopen it in a write or read mode. 


Suppose a path has several producers and consumers connected to it and 
is in an open state. If all producers close, then the consumers will 
receive an end-of-file status once all buffered data has been 
consumed. To clear this end-of-file status, each consumer must 
acknowledge its receipt by entering a closed state. Any process 
attempting to open a file connected to a path at end-of-transmission 
will be suspended until all consumers have closed. 


If all consumers connected to a path enter a closed state, producers 
are not required to close. In general, they will_become suspended due 
unconsumed buffers of data and will not be able to proceed until a 
consumer opens and begins processing buffers. 


If a file that is consuming data is closed before reaching 
end-of-file, it is possible that some transmissions will be discarded. 
This will occur if the last producer connected to a path has_' closed 
after transmitting data and the last consumer decides to close without 
processing the data. In such a situation IPCSCLOSE must assume that no 
Other consumer will connect to the path and as a consequence must 
discard all unreceived data so buffers can be reclaimed. 


4.6 USE OF DUMMY SUBSYSTEM ENTRY POINTS 


The following file service requests are not meaningful in the IPC 
Subsystem: 


@ ABORTIO 
@ DELETE 

@ POSITION 
e STATUS 


Dummy or "NO-OP" routines are provided for these services to conform 
to I/O Subsystem interface requirements. The dummy entry points are 
placed in the I/O Service Directory in place of the entry points for 
the above services. 3 
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Refer to Appendix D for more 
Dummy Subsystem entry points. 


information on 


4-16 


implementation 





“A 


) 
So" 














SECTION V 
ENCODE AND DECODE ROUTINES 


5.1 . GENERAL 


Encode and decode routines are supplied in the Device Independent File 
I/O Package to enable the assembly language user to perform data 
conversions from the internal representation to printable format and 
conversely from the printable format to internal representation (these 
routines are executed transparently for the Pascal user in the 
Microprocessor Pascal Executive). This capability is useful when 
primitive data is to be printed or data is to be input via a keyboard. 


For each of the routines described, the calling parameters generally 
Fit into a convenient template (with some exceptions that are noted in 
the individual procedure descriptions). This template is presented 
below. The user should refer to this template to understand the 
procedure definitions and calling sequences. 


Parameter ‘Definition Limits Input/Output 
String Pointer to the output Integer Input 
Pointer string array (Encode) 

and the input string array 

Decode). 
String The number of bytes in Integer Input 
Length the “String” parameter. | 
Index The starting position Integer Input/Output 


of output field (for 
Encode routines) or 

input field (for Decode 
routines). Upon return, 
this field will contain 
the position of the char- 
acter following the output 
field (Encode ) or follow- 
ing the input field (De- 
code). This facilitates 
encoding or decoding mul- 
tiple numbers into one 
string. This parameter 

is always passed by ad- 
dress. 








Status An integer containing a Integer Output 
status message. Upon 
return, this integer con-. 
tains a zero if the enco- 
ding or decoding was suc- 
cessful; a non-zero status 
indicates that the input 
Parameters are contradic- 
tory or the result will 
not fit into the speci- 
fied output field. This 
Parameter is always passed 
by address. | 


Input Data The address of the data Integer Input 
Or Result being encoded or the re- 

Sult of a decode (passed 

by address) 


Width The width in bytes of Integer 3 Input 
the output field in | 
Encode and of the input 
field in Decode. 


5.2 ENCODE ROUTINES 
Encoding is the process of converting from an internal format to a 
character string. Routines accomplishing this are defined below. 


5.2.1 Encoding an Integer (ENCSIN) 


ENCSIN is used to convert from an integer to character format. One 
additional parameter is passed to ENCSIN: Hex which is a Boolean 


value. If Hex is True, a hexadecimal value is generated. When Hex is 
False, a decimal results. 


The assembly language calling sequence follows: 
Assume: The parameters for this procedure are stored at the 


following displacements into the calling procedures 
local frame: | 


String Pointer at 0 
String Length at 2 
Index at 4 
Status at 6 
Input Data Address at 8 
Width , at 10 
12 


Hex at 








MOV *LF,*SP+ ‘PASSING STRING POINTER 


MOV @2(LF) ,*SP+ PASSING STRING LENGTH 
MOV LF,*SP | PASSING INDEX 

A @FOUR (LF) , *SP+ : 

MOV LF,*SP PASSING STATUS 

A @SIX (CODE) ,*SP+ 

MOV LF,*SP PASSING INPUT DATA ADDRESS 
A @EIGHT (CODE) ,*SP+ 

MOV @10(LF) ,*SP+ PASSING WIDTH 

MOV @12(LF) ,*SP+ PASSING HEX 


DATA CALLS 
DATA ENCSIN 


where the following sequence is in the user’s code: 


MOD EQU $ MOD LABELS BEGINNING OF LOCAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


FOUR EQU $-MOD 


DATA 4 
SIX EQU $-MOD 
DATA 6 
EIGHT EQU $-MOD 
DATA 8 


EXCEPTIONS AND CONDITIONS: 


. Possible errors resulting (by error code): 


(1) Bad parameter passed to routine. An example is the Index 
Parameter exceeding the parameter for String Length. 


(2) Field width too large. This occurs when Index plus Width minus 
one byte exceeds String Length. 


5.2.2 Encoding a Longint (ENC$LO) 


ENCSLO is called to convert from an extended integer to character 
format. As in ENCSIN (above) a Hex parameter is passed to ENCSLO 
indicating if the result is to be hex (parameter value is True) or 
decimal (parameter value is false). 


The assembly language calling sequence follows: 
Assume: The parameters for this procedure are stored at the 


following displacements into the calling procedure’s 
local frame: 





String Pointer at 


0 

String Length | at 2 

Index at 4 

Status at 6 

Input Data Address at 8 

Width | at 10 

Hex | at 12 
MOV *LF ,*SP+ PASSING STRING POINTER 
MOV @2(LF) ,*SP+ PASSING MAXIMUM NUMBER 
MOV  LF,*SP PASSING INDEX 
A @FOUR (LF) ,*SP+ 
MOV LF ,*SP PASSING STATUS 
A @SIX (CODE) ,*SP+ | 
MOV. LF,*SP PASSING INPUT DATA ADDRESS 
A @EIGHT (CODE) ,*SP+ 
MOV @10(LF) ,*SP+ PASSING WIDTH 


MOV @12(LF) ,*SP+ PASSING HEX 
DATA CALLS | 
DATA ENCSLO 


where the following sequence is in the user”s prologue: 


MOD EQU $ MOD LABLES BEGINNING OF LOCAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


FOUR EQU $-MOD 


DATA 4 
SIX EQU $—-MOD 
DATA 6 
EIGHT EQU $-MOD 
DATA 8 


EXCEPTIONS AND CONDITIONS: 


Possible errors resulting (by error code): 


(1) Bad parameter passed to routine. An example is the Index 


Parameter exceeding the parameter for String Length. 


(2) Field width too large. This occurs when Index plus Width minus 
one byte exceeds String Length. 


5.2.3 Encoding Boolean (ENCSBO) 


The ENCSBO routine is called to convert from the internal Boolean to 
character format. If the byte width of the output field is less than 
five, then TRUE is encoded as "T" and FALSE as "F"; otherwise, TRUE 
and FALSE are spelled out. 
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The assembly language calling sequence follows: 


Assume: The parameters for this procedure are stored at the 
following displacements into the calling procedures 


local frame: : 


String Pointer 
String Length 
Index 

Status 

Input Data Address 
Width 


MOV *LF,*SP+ 
MOV @2 (LF) ,*SP+ 
MOV LF,*SP 


A @FOUR (LF) ,*SP+ 
MOV LF ,*SP 

A @SIX (CODE) ,*SP+ 
MOV LF, *SP 

A @EIGHT (CODE) ,*SP+ 


MOV @i0O(LF) ,*SP+ 
DATA CALLS 
DATA ENCSBO 


at 
at 
at 
at 
at 
at 


PASSING 
PASSING 
PASSING 
PASSING 
PASSING 


PASSING 


rOonm NO 


0 

STRING POINTER 
STRING LENGTH 
INDEX 

STATUS 

INPUT DATA ADDRESS 


WIDTH 


where the following sequence is in the user’s prologue: 


“~ MOD EQU S$ | MOD LABELS BEGINNING OF LOCAL DATA 


DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


FOUR EQU S$-MOD 


DATA 4 
SIX EQU  $-MOD 

DATA 6 
EIGHT EQU $-MOD 

DATA 8 


EXCEPTIONS AND CONDITIONS: 


Possible errors resulting (by error code) : 


(1) Bad parameter passed to 


routine. An example is the Index 


Parameter exceeding the parameter for String Length. 


(2) Field width too large. This occurs when Index plus Width minus 
one byte exceeds String Length. 














59-2.4 Encoding a Character (ENCSCR) | | , 


ENCSCR is called to store a single character (padded with blanks on =) 
the left) in a string. The character is right justified. in the output ~~ 
field. 


The assembly language calling sequence follows: 


“Assume: The parameters for this procedure are stored at the 
following displacements into the calling procedure’s 
local frame: 


String Pointer a at 0 

String Length at 2 

Index _ at 4 

Status at 6 

Input Data Address at 8 

Width at 10 
MOV *LF,*SP+ PASSING STRING POINTER 
MOV @2(LF) ,*SP+ PASSING STRING LENGTH 
MOV LF, *SP PASSING INDEX 
A @FOUR (LF) ,*SP+ 
MOV LF, *SP 7 PASSING STATUS 
A @SIX (CODE) ,*SP+ | 
MOV LF,*SP PASSING INPUT DATA ADDRESS 
A @EIGHT (CODE) ,*SP+ 


MOV @10(LF) ,*SP+ PASSING WIDTH oe 
DATA CALLS | | | 
DATA ENCSCR 


where the following sequence is in the prologue of the user”s code: 


MOD EQU-) $ MOD LABELS BEGINNING OF LOCAL DATA | 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 
FOUR EQU $-MOD 
DATA 4 
SIX EQU $-MOD 
DATA 6 


EXCEPTIONS AND CONDITIONS: 
Possible errors resulting (by error code): 
(1) Bad parameter passed to routine. An example is the Index 


Parameter exceeding the parameter for String Length. 


(2) Field width too large. This occurs when Index plus Width minus 
one byte exceeds String Length. 


5.2.5 Encoding a String (ENCSST) 


The routine ENCSST is called to store a character string in a field 
within another character string. One additional parameter passed _ to 
this routine is the width in bytes of the input field. The assembly 
language calling sequence follows: 


Assume: The parameters for this procedure are stored at the 
following displacements into the calling procedure’s 
local frame: | 


String Pointer at 0 

String Length at 2 

Index at 4 

Status | at 6 

Input Data Address at 8 

Input Width at 10 

Output Width at 12 
MOV *LE ,*SP+ PASSING STRING POINTER 
MOV @2(LF) ,*SP+ PASSING STRING LENGTH 
MOV LF,*SP | PASSING INDEX 
A @FOUR (LF) ,*SP+ 
MOV LF ,*SP | PASSING STATUS 
A @SIX (CODE) ,*SP+ | | 
MOV LF, *SP PASSING INPUT DATA ADDRESS 
A @EIGHT (CODE) ,*SP+ 
MOV @10(LF) ,*SP+ PASSING INPUT WIDTH 
MOV @12 (LF) ,*SP+ PASSING OUTPUT WIDTH 


DATA CALLS 
DATA ENCSST 


where the following sequence is in the user”’s prologue: 


MOD EQU $ MOD LABELS BEGINNING OF LOCAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


FOUR EQU $-MOD 


DATA 4 
SIX EQU $-MOD 
DATA 6 
EIGHT EQU S-MOD 
DATA 8 


EXCEPTIONS AND CONDITIONS : 
Possible errors resulting (by error code): 
(1) Bad parameter passed to routine. An example is the “Index 


Parameter exceeding the parameter for String Length. 


(2) Field width too large. This occurs when Index plus Width minus 





one byte exceeds String Length. 


5.2.6 Encoding a Real (ENCSRE) 


ENCSRE is called to convert from the internal representation of a real 


to its corresponding character format. One additional parameter is . 


passed to this routine. This parameter, F, represents the number of 
digits falling to the right of the decimal. If F < 0, then the output 
is in floating point format. To generate output in fixed point format, 
set F to the number of digits to the right of the decimal point (i.e., 
number of decimal places). Otherwise, set F less than 0 for floating 
point format. : 


Assume: The parameters for this procedure are stored at the 
following displacements into the calling procedure’ s 
local frame: 


String Pointer at 0 
String Length at 2 
Index | at 4 
Status at 6 
Input Data Address at 8 
Output Width at L0 
F at 12 
MOV *LF,*SP+ - PASSING STRING POINTER 
MOV @2(LF) ,*SP+ PASSING STRING LENGTH 
MOV LF,*SP PASSING INDEX 
A @FOUR (LF) ,*SP+ 
MOV LF ,*SP PASSING STATUS 
A @STX (CODE) ,*SP+ | 
MOV LF,*SP PASSING INPUT DATA 
A @EIGHT (CODE) ,*SP+ 
MOV @10(LF) ,*SP+ PASSING OUTPUT WIDTH 
MOV @12(LF) ,*SP+ PASSING F 


DATA CALLS 
DATA ENCSRE 


| where the following sequence is in the user’s prologue: 


MOD EQU S$ MOD LABELS BEGINNING OF LOCAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


FOUR EQU $-MOD 


DATA 4 
SIX EQU S$-—MOD-: 
DATA 6 
EIGHT EQU $-MOD 
DATA 8 


EXCEPTIONS AND CONDITIONS: 
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Any error in the parameters will result in status being set to 1. In 
this event, the output field will be set to all asterisks (°***... )e 


59-3 DECODE ROUTINES 


Decoding is’ the process of converting from a character string to an 
internal format. 


5.3.1 Decoding an Integer (DECSIN) 


DECSIN is called to convert a field in a character string to an 
integer. If the number is preceded by a “#°, it is interpreted as a 
hexadecimal number, otherwise decimal is assumed. The assembly 
language calling sequence follows: 


Assume: The parameters for this procedure are stored at the 
following displacements into the calling procedure’ s 
local frame: 


String Pointer at 0 

String Length at 2 

Index at 4 

Status at 6 

Address of Result at 8 

Input Width — at 10 
MOV *LF,*SP+ PASSING STRING POINTER ; 
MOV @2 (LF) ,*SP+ PASSING STRING LENGTH 
MOV LF, *SP PASSING INDEX 
A @FOUR (LF) ,*SP+ 
MOV LF ,*SP PASSING STATUS 
A @SIX (CODE) , *SP+ 
MOV LF,*SP PASSING RESULT ADDRESS 
A @EIGHT (CODE) ,*SP+ | 
MOV @1O(LF) ,*SP+ PASSING INPUT WIDTH 


DATA CALLS 
DATA DECSIN 


where the following sequence is in the user’s code: 


MOD EQU) $ MOD LABELS BEGINNING OF LOCAL DATA 
DATA PRO-MOD | PRO LABELS BEGINNING OF EXECUTABLE CODE 


FOUR EQU $-MOD 


DATA 4 
SIX EQU $-MOD 
DATA 6 
EIGHT EQU $-MOD 
os DATA 8 — 





EXCEPTIONS AND CONDITIONS: 


Possible errors resulting (by error code): 


(1) Bad parameter passed to routine. An example is the Index 


(2) 


(3) 


(4) 


(5) 


Dede2 


Parameter exceeding the parameter for String Length. 


Field width too large. This occurs when Index Plus Width. minus 
one byte exceeds String Length. 


Incomplete Data. An example is a plus sign without digits 
following. | 


Invalid character in field. This happens when a non-numeric 
character is found in a number. | 


Data value too large. This occurs when a number is too large to 


be stored in the given variable (e.g., 32768 is an integer). 


Decoding a Longint (DEC$LO) 


The procedure DECSLO is called to convert a field in a character 
string to an extended integer. If the number is preceded by a “#°, it 
is interpreted as a hexadecimal number, otherwise decimal is assumed. 
The assembly language calling sequence follows: 


Assume: The parameters for this procedure are stored at the 


following displacements into the calling procedure’s 
local frame: 


String Pointer at 0 
String Length bs at 2. 
Index at 4 
Status at 6 
Address of Result at 8 
Input Width at 10 


eee ts Sha 

















MOV *LF,*SP+ _ PASSING STRING POINTER 


MOV @2 (LF) ,*SP+ PASSING STRING LENGTH 
MOV LF ,*SP | PASSING INDEX 

A @FOUR (LF) ,*SP+ 

MOV LF,*SP PASSING STATUS 

A @SIX (CODE) ,*SP+ 

MOV LF ,*SP PASSING ADDRESS OF RESULT 
A @EIGHT (CODE) ,*SP+. 

MOV @10 (LF) ,*SP+ PASSING INPUT WIDTH 


DATA CALLS 
DATA DECS$LO 


where the following sequence is in the user’s code: 


MOD EQU $ MOD LABELS BEGINNING OF LOCAL DATA |. 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


FOUR EQU $-MOD 


DATA 4 
SIX EQU $-MOD 
DATA 6 
EIGHT EQU $-MOD 
DATA 8 


EXCEPTIONS AND CONDITIONS: 
Possible errors resulting (by error code): 


(1) Bad parameter passed to routine. An example is the Index 
Parameter exceeding the parameter for String Length. 


(2) Field width too large. This occurs when Index eae Width minus 
one byte exceeds String Length. 


(3) Incomplete Data. An example is a plus’. sign without digits 
following. | 


(4) Invalid character in field. This happens when a non-numeric 
character is found in a number. 


(5) Data value tao large. This occurs when a number is too large to 
be stored in the given variable (e.g., decoding a number larger 
than #7FFFFFFF) . 


5.3.3 Decoding Boolean (DECS$BO) 


The procedure DECSBO is called to convert a field in a Boolean 
character string to an integer. Valid boolean strings are “7? , “TRUE, 
“F*, and “FALSE” No conversion of lower to upper case is done. The 
assembly language calling sequence follows. 
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Assume: The parameters for this procedure are stored at the 
following displacements into the calling procedures Y 
:' local frame: | oe. 
String Pointer 7 | at 0 
String Length at 2 
Index at 4 
Status _ | at 6 
Address of Result _ at 8 
Input Width | at 10 
MOV *LF,*SP+ PASSING STRING POINTER 
MOV @2(LF) ,*SP+ PASSING MAXIMUM NUMBER 
._MOV LF ,*SP , PASSING NUMBER 
A @FOUR (LF) ,*SP+ 
MOV LF,*SP PASSING STATUS 
A @Q@SIX (CODE) ,*SP+ 
MOV LF,*SP PASSING ADDRESS OF RESULT 
A @EIGHT (CODE) , *SP+ i a 
MOV @1O(LF) ,*SP+ PASSING INPUT WIDTH 


DATA CALLS 
DATA DECSBO 


where the following sequence is in the user’s code: 


MOD EQU $ MOD LABELS BEGINNING OF LOCAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 
FOUR EQU $-MOD - 
DATA 4 
SIX  EQU $-MOD 
DATA 6 
EIGHT EQU $-MOD 
DATA 8 
EXCEPTIONS AND CONDITIONS: . 
Possible errors resulting (by error code): 
(1) Bad parameter passed to routine. An example is the Index ’ 
| Parameter exceeding the parameter for String Length. | 
(2) Field width too large. This occurs when Index plus Width minus 
one byte exceeds String Length. 
(3) Invalid character in field. This happens when an invalid 
separator is found. | 
5.3.4 Decoding a Character (DECSCH) 
The procedure DECSCH is called to convert a field in a character ) 








string to an integer. In passing the byte width of the input field 
(Ww), if W> 0, the first non-blank character in the next W characters 


is returned. If the field is all blanks, a blank is returned. If 


w= 0, a blank is returned. If W < 0, the field width is assumed to be 
1 (i.e. the next character is. returned, blank or not). 


The assembly language calling sequence follows: 
Assume: The parameters for this procedure are stored at the 


following displacements into the calling procedures 
local frame: | 


String Pointer at 0 
String Length at 2 
Index at 4 
Status at 6 
Address of Result at 8 
Input Width at 10 
MOV *LF,*SP+ ‘¢ PASSING STRING POINTER 
MOV @2 (LF) ,*SP+ PASSING STRING LENGTH 
MOV LF,*SP PASSING INDEX 
A @FOUR (LF) ,*SP+ 
MOV LF,*SP PASSING STATUS 
A @STX (CODE) ,*SP+ 
MOV LF, *SP PASSING ADDRESS OF RESULT 
A @EIGHT (CODE) ,*SP+ 
MOV @10(LF) ,*SP+ PASSING INPUT WIDTH 
DATA CALLS | : 


DATA DECSCH 


where the following sequence is in the users code: 


MOD EQU $ MOD LABELS BEGINNING OF LOCAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


FOUR EQU $-MOD 


DATA 4 
SIX EQU  $-MOD 

DATA 6 
EIGHT EQU $-MOD 

DATA 8 — 


EXCEPTIONS AND CONDITIONS: 
Possible errors resulting (by error code): 


(1) Bad parameter passed to routine. An example is the Index. 
Parameter exceeding the parameter for String Length. 


(2) Field width too large. This occurs. when Index plus Width minus 
one byte exceeds String Length. <- 
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5.3.5 Decoding a String (DEC$ST) 


DECSST is called to move a field in a character string to another 
character string. One additional parameter is passed to DECSST: the 
length of the result string. 


The assembly language calling sequence follows: 


Assume: 


MOV 
MOV 
MOV 
A 
MOV 
A 
MOV 
A 
MOV 
MOV 
DATA 
DATA 


The parameters for this procedure are stored at the 


following displacements into 
local frame: 
String Pointer , at 
String Length at 
Index | at 
Status at 
Address of Result at 
Output Length at 
Input Field Width at 
*LF,*SP+. PASSING 
@2 (LF) , *SP+ | PASSING 
LF,*SP | PASSING 
@FOUR (LF) , *SP+ 7 
LF ,*SP PASSING 
@SIX (CODE) ,*SP+ 
LF,*SP . PASSING 
@EIGHT (CODE) ,*SP+ 
@LO(LF) ,*SP+ PASSING 
@12(LF) ,*SP+ PASSING 
CALLS 
DECSST 


the calling procedures 


FPrHOnR NO 


0 
2 
STRING POINTER 
STRING LENGTH — 
INDEX 

STATUS 

RESULT ADDRESS 


OUTPUT LENGTH 
INPUT WIDTH 


where the following sequence is in the user’s code: 


MOD EQU 


DATA PRO=-MOD 


FOUR EQU 


$ MOD LABELS BEGINNING OF LOCAL DATA 


$-MOD © 


DATA 4 


SIX EQU 


S—MOD 


DATA 6 


EIGHT EQU 


S—MOD 


DATA 8 


EXCEPTIONS AND CONDITIONS: 


PRO LABELS BEGINNING OF EXECUTABLE CODE 


Possible errors resulting (by error code): 


(1) Bad parameter passed to routine. An example is the Index . 


Parameter exceeding the parameter for String Length. 
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(2) Field width too large. This occurs when Index plus Width minus 
one byte exceeds String Length. 


5.3.6 Decoding a Real (DECSRE) 
The DECSRE routine is called to convert from a character string 
providing the printable representation of a Real number to its 
internal floating point format. 
The assembly language calling sequence follows: 

Assume: The parameters for this procedure are stored at the 


following displacements into the calling procedure’s 
local frame: 


String Pointer at 0 
String Length at 2 
Index at 4 
Status - at 6 
Address of Resul at 8 
Width 3 at 10 
MOV *LF,*SP+ PASSING STRING POINTER 
MOV @2 (LF) ,*SP+ PASSING STRING LENGTH 
MOV LF,*SP PASSING INDEX 
A @FOUR (LF) ,*SP+ | 
MOV LF,*SP PASSING STATUS 
A @SIX (CODE) , *SP+ 
MOV LF,*SP PASSING RESULT ADDRESS 
A @EIGHT (CODE) ,*SP+ 
MOV @1LO(LF) ,*SP+ ~ PASSING WIDTH 


DATA CALLS 
DATA DECSRE 


where the following sequence is in the user”s code: 


MOD EQU $ MOD LABELS BEGINNING OF LOCAL DATA 
DATA PRO-MOD PRO LABELS BEGINNING OF EXECUTABLE CODE 


FOUR EQU S-=-MOD 
DATA 4 

SIX EQU S$=MOD 
DATA 6 


5-15 








EXCEPTIONS AND CONDITIONS: a : | | 


If the input parameters are contradictory, the status will be set to oe 
one . . beat 


If the field specified is not contained in the array (i.e., the field 
width is too large) the status is set to two. 


If the field does not contain a valid real number, the status is set. 
to three. 


SECTION VI 
CONFIGURING AN APPLICATION TO INCLUDE DIF I/O ROUTINES 


6.1 GENERAL 


The paragraphs that follow provide information on initializing and 
configuring an application containing the File I/O Decoder and various 
I/O Subsystems. The main points presented include a description of 
system initialization, detail on the various object modules used to 
build the target application, and an overview of the link editing 
process. The default version of the GHOSTS process, a sample CONFIG 
module, and an example Link Edit Control File are also presented. 


The link editor present in the user’s development system provides the 
means for generating the target application (or load module). The user 
specifies a link edit control file as input for the link editor. The 


link editor resolves all of the application’s external references via 


the libraries specified in the link edit control file. 


Detailed information regarding configuring a load module for native 
code execution is. presented in the Realtime Executive User”’s Manual 

(MP373) for the assembly language user and the Microprocessor Pascal 
Executive User”’s Manual (MP385) for the Pascal user. 


6.2 INITIALIZATION 


‘ Initialization of applications configured with one or more I/O 


Subsystems and the File I/O Decoder takes place automatically at power 
up time. The GHOSTS process supplied by the run-time support contains 
a call to DSINIT, the entry point for initialization present in the 
File I/O Decoder. In turn, each of the I/O Subsystems present on the 
target system is initialized via DSINIT. If the user wishes to 


activate the File I/O Decoder and the suported I/O Subsystems directly 


from his application, he can remove the call to DSINIT from GHOSTS. 


In addition, GHOSTS contains a call to MSGSINIT which identifies the 
name of the device acting as the destination of the standard procedure 
MESSAGE. The statement: 


MESSAGE( “Execution begins.” ); 


can be’ inserted after the START statement in the user application to 
Signal the "Operator" (specified in the default version of GHOSTS) 
that execution has begun. To implement this call, the node name 
"Operator" must be present in a Port Contstants Record associated with 
some I/O Subsystem on the target ("Operator" is the node name assigned 
to a device in a Port Constants Record in the Operator Interface I/0 
Subsystem--see Appendix A). If this node name is not so specified, its 
reference must be removed from GHOSTS. Note also that IPC Subsystem 
will always claim the name “Operator” if that name is not claimed by 
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any Other subsystem. 


For most applications the default version of GHOSTS will be adequate. 
If certain initialization must be performed for a _class- of 


applications (e.g. special devices must be initialized), it is” > 
appropriate that it be performed in the ghost procedure so it need not, 


be repeated in each application. If it is known that the File I/O 
Decoder will not be used, then a slight savings in code space can be 
made by removing the calls to DSINIT in GHOSTS. If the standard 
procedure MESSAGE will not be used, the call to MSGSINIT can also be 
removed from GHOSTS. If the File I/O Decoder is not specified at link 
edit time, DSINIT will be resolved by a "dummy" routine (present in 
the Rx Sequential Library RXOBJ) that performs no processing. 


The default version of GHOST$ is displayed below (the source for 
GHOSTS is written in assembly language). 
system ghostSsystem; 


const 
dont_care = 2; 


type | | 
dummy buffer = packed array[ 1..dont_care ] of char; 


procedure dSinit; external; 


procedure msgSinit( var pathname: dummy_buffer; length: integer ); 


external; 
Program systm$; external; 


procedure ghost$; 
var 
pathname: packed array[ 1..8 ] of char; 
begin 
dSinit; 
Pathname := “OPERATOR”; 
msgSinit( pathname: :dummy buffer, size( pathname ) ); 
start systm$; 
end { ghosts |}; 


begin 
$ nullbody. |} 
end. 


FIGURE 6-1. DEFAULT VERSION OF PROCEDURE GHOSTS 


6.3 CONFIGURATION MODULES 


The object modules required to configure an application with the File 
I/O Decoder and the I/O Subsystems provided in MPX and in the Device 
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Independent File I/O Package are described below. 


6.3.1 DIF I/O Routines 


The File I/0 Decoder, the Operator Interface I/0 Subsystem, the 
Interprocess Communication I/O Subsystem, and the Encode and Decode 
routines are packaged as sequential libraries as described below. 
These libraries are supplied for the Pascal user in the Microprocessor 
Pascal Executive and for the assembly language user in the Device 
Independent File I/O Package. 


@® DSOBJ containing object modules to support the File I/O 
Decoder level of device-independent I/O (described in 
Section III). This library also contains the dummy I/0 
Subsystem (described in Appendix D) used when a_e specific 
file service is not supported on the target. 


@ IPCSOBJ containing object modules comprising the 
Interprocess Communication I/O Subsystem (described in 
Section IV). IPCSOBJ uses routines from the libraries 
CSOBJ (supplied in MPX or Rx) and DSOBJ. Because IPCSOBJ 
accepts any pathname passed at Connect time, it should be 
the last I/O Subsystem referenced in the I/0 Subsystem 
Service Directory (IODIR) specified in CONFIG (see 
Subsection 6.3.3 below). 


e® TO2SOBJ containing object modules comprising the Operator 
Interface 1/0 Subsystem (described in Appendix A). These 
routines support communication with a variety of terminals 
connected to a 9902 interface. Routines from the libraries 
CSOBJ and DSOBJ are also required by the TO2SOBJ library. 


e DESOBJ containing object modules that implement Decode and 
Encode routines (described in Section V). 


NOTE: The run-time support library MPPSOBJ providing data types 
routines is supplied to the assembly language programmer in the DIF 
I/O package. The Pascal user can find this library in the 
Microprocessor Pascal Executive. 


6.3.2 The Executive Library 


The libraries providing native code run-time support consist of the 


sequential library RXSOBJ and the random library RXSLIB, each. 


containing miscellaneous Rx routines; and the sequential libraries 
CSOBJ, CLKSOBJ, and MPPSOBJ containing channel routines, clock 
routines, and Data Types routines respectively. With the exception of 
CLKSOBJ, the above run-time support libraries are required in most 
applications utilizing DIF I/0 software. The Microprocessor Pascal 
Executive supplies these libraries to the Pascal user. The assembly 
language user obtains all native code libraries except for the library 
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MPPSOBJ from the Realtime Executive (Rx). MPPSOBJ is supplied to the 
assembly language programmer in the DIF I/O package. _ 


6.3.3 CONFIG 


CONFIG is provided in the native code run-time support (MPX and _ RX). 
The default version of this module must be customized to fit the 
user’s application. Information regarding this module is contained in 
the Microprocessor Pascal Executive User”s Manual and in the Realtime 
Executive User’s Manual. The Information below describes data required 
in CONFIG when the load module will contain DIF I/O routines. 


6.3.3.1. Specification of the I/O Service Directory. The default 


version of CONFIG provides for the specification of the I/O Service 
Directory used during system initialization at power up time. In this 
directory, the user specifies the address of an I/O Subsystem 
Directory and the address of an initial Port Constants Record for each 
I/O Subsystem supported on the target. The I/O Subsystem Directory | 
contains the entry points for the routines making up the 1I/0 
Subsystem. These entry points are standard from I/O Subsystem to I/O 
Subsystem (see Subsection 2.4.2 for information on the derivation of 
entry point names and Appendix B for a picture of the I/O Subsystem 
Directory). The Port Constants Record contains fixed data describing 
the port associated with an I/O Subsystem. The port provides’ the 
logical connection between the I/O Subsystem and the CPU; in many 1/0 
Subsystems the port is associated with some device controller (see 
Appendix B for more information regarding the Port Constants Record). . 
While it is not required, the Port Constants Record(s) and the Node 
Constants Record it points to can be conveniently placed in the CONFIG 
module. | 


The end of the I/O Directory is marked by a null entry. 


Sample code used in the I/O Directory in CONFIG is presented below. In 
the example, entries are present for two I/O Subsystems: the Operator 
Interface (T02) I/O Subsystem described in Appendix A and the 
Interprocess Communication (IPC) I/O Subsystem described in Section 
IV. Note that the pointer to the Port Constants Record for the 
Interprocess Communication I/O Subsystem is set to nil. The sample 
CONFIG module below also contains the Port Constants Record and Node 
Constants Records required by the Operator Interface I/O Subsystem. 











IODIR EQU $§ 
* 


REF TO2SSD, 
DATA TO2SSD,TO2SPC 


REF 


IPCSSD 


DATA IPCSSD,0 


DATA 0 


6.3.3.2 Example CONFIG. An 


Subsystems are specified in 


Interface 
Subsystem. 


I/O Subsystem 


I/O DIRECTORY 


T02 SERVICE DIR. AND PORT CONSTANTS REC. 


IPC SERVICE DIRECTORY 


LIST TERMINATOR 


example CONFIG is presented below. Two 1/0 
the I/O Service Directory: the Operator 
and the Interprocess Communication 1/0 





IDT “CONFIG” SPECIFY CONFIGURATION 





eee et ee He HF HE HF F 


REVISION: 08/01/80 1.00 ORIGINAL FOR RX 2.0 
ROUTINE LIST: CONFIG, IWPSO .. IwP$15, BADSWP, 
SRAMTB, SRESTA,. SLREX, $SYSCR, 
SDEFAU, SFILL, S$STKSZ, $BOOTP, 
SIODIR, DBSWP | 
COPY MODULES: 
NONE. 
MACRO DEFINITIONS: 
NONE. 
EXTERNAL ROUTINES: 
NONE. 
EXTERNAL DATA: 
PSEG | | | 3 . 
* MODULE CONSTANTS: 
IWPSZ EQU 24 EXAMPLE SIZE OF AN INTERRUPT 
* WORKSPACE (R4-RL5) 
LOWRAM EQU »>8000 LOW BOUNDARY OF RAM 


* MODULE VARIABLES: 
x 


DORG LOWRAM 
¥ 
DEF IWPS0,IWPS1,IWP$2,IWPS3 
DEF IWPS4,IWPS5,IWPS6,IWPS7 
DEF IWPS8,IWPS9,IWPS10,IWPS11 
DEF IWPS12,IWPS$S13,IWP$14,IWPS15 
DEF BADSWP,DBSWP 
IWPSO BSS 
IWP$1 BSS 32 
DBSWP EQU IWPSI1 = 


IWPS2 EQU $-32+IWPSZ he 
BSS IWPSZ 
IWP$S3 EQU $-—32+IWPSZ 
BSS IWPSZ 
IWPS4 EQU $-32+IWPSZ 
BSS IWPSZ 
IWPS5 EQU $—-32+IWPSZ 
BSS IWPSZ 
IWPS6 EQU $-32+IWPSZ 
BSS IWPSZ 
IWPS7 EQU $—32+IWPSZ 
BSS IWPSZ 
IWPS8 EQU S$—32+IWPSZ 
BSS IWPSZ 
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IWPS9 EQU $-32+IWPSZ 


BSS IWPSZ 
IWPS10 EQU $-32+IWPSZ 
BSS IWPSZ 
IWPS11 EQU $-32+IWPSZ 
BSS IWPSZ 
IWPS$12 EQU $=-32+IWPSZ 
BSS IWPSZ 
IWP$S13 EQU $-32+IWPSZ 
BSS IWPSZ 
IWPS$14 EQU $-32+IWPSZ 
BSS IWPSZ 
IWPS15 EQU $-32+IWPSZ 
BSS IWPSZ 


BADSWP BSS 32 
* 

LOWHP EQU $ 
* 


RORG 7 
TITL “CONFIG: SPECIFY CONFIGURATION 
PAGE 

ABSTRACT: 
SPECIFY CERTAIN SYSTEM PARAMETERS, THE RAM 
CONFIGURATION, AND THE I/O SUBSYSTEM 
DIRECTORY. | 

CALLING SEQUENCE: 
NONE. 

EXCEPTIONS AND CONDITIONS: 
NONE. 

LOCAL DATA: 
NONE. 

ENTRY POINT: 

NONE. 
KEKEKEKEKEKERKRKEEEKEEKEKEEKEEKREEKEEKEKEEEKEKEKEEEEEKEEKKEKEKRKREK 
* ADDRESS OF THE "BLWP" VECTOR FOR RESTARTS; USE "0" FOR 
* LEVEL 0 INTERRUPT, ">FFFC" FOR THE "LREX" VECTOR, OR 
* THE ADDRESS OF A USER-DEFINED VECTOR. 

JESSIE GIGI GCC CIOS O GGG GCIOC COSI S IO IO COC IOI IOI 
DEF SRESTA 
SRESTA DATA 0 


e+ FF FF F FF FE OF OF 
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KHAKI KRRKKRKEE 


* ADDRESS OF THE "BLWP" VECTOR FOR THE "LREX" INSTRUCTION; 

* USE "0" IF THERE IS TO BE NO "LREX" VECTOR OR IF HIGH 

* MEMORY IS ROM. 

RREKKKKEEEKEEE EERE KKEEEKEREE EKER REREREREREEEEKEKEERERKKKKKREKRER 
| DEF SLREX 

SLREX DATA 0 

5k EK KERER ERAS ERERERERERAES ERE RELERE EERE KEE 


* ADDRESS OF THE USER-DEFINED ROUTINE TO BE INVOKED IN CASE 


* OF A SYSTEM CRASH; USE "0" FOR THE SYSTEM DEFAULT WHICH 


* IS TO MASK INTERRUPTS AND IDLE THE PROCESSOR. 
KRkeKkRRKKRRRRRKRKRKRK RRR KKRKRKRKRKRKKRRKRKRKKRKRKKRKRKKKKRK Raa KEKE 
DEF SSYSCR 


SSYSCR DATA 0 
HHEKKKKKKEKKKKEKKKEEKKREKRKKEKEKEEEKEKKKRKRKKKRKKKKKKKKKRKKKKKKKRKKKKEKEK 


-* ADDRESS OF THE MPP ROUTINE TO BE INVOKED IF AN EXCEPTION 


* OCCURS BUT NO EXCEPTION HANDLER HAS BEEN SPECIFIED; USE 
* "0" FOR THE SYSTEM DEFAULT WHICH IS A "NO EXCEPTION 
* HANDLER" SYSTEM CRASH. . 


RIKER KKK KKK KKK KKK KKK 


DEF S$DEFAU 


SDEFAU DATA 0 
KRKKKKKEKEKER RAKE KKEKREKEKREKREKEEKKKK RRR KKK 


* THIS IS THE VALUE WITH WHICH THE HEAP WILL BE 


* INITIALIZED AT POWER-UP. 

FOI S OIC IO RCI GIIGOCCCIOCCCICCCCCOO CCCI CCCI IIIT IT 
DEF SFILL 

SFILL JMP $§$ 


kKkkeKKKKKKRKRRRKKKKRKRKRKRKRKRKKRKRKKRKRKKKRKKKRKRKKKKKKRAKKKKKRKRRKRKRKRKRKRRKEK 


* THIS IS THE DEFAULT STACK SIZE (IN WORDS) THAT IS USED 

* IF A "STACKSIZE" CONCURRENT PARAMETER IS NOT SPECIFIED. 
HH IK HII KIKI KIRKE RIKER KEKE EERE KEKE ERE ERE RHR KR EE 

DEF S$STKSZ 

SSTKSZ DATA >100 

KERR KKK KKK KK KIRKE IRI RR ERE SRRRRREEEKEEKE 
* THE PARAMETER LIST FOR THE CALL TO " SSPRCS" TO START THE 
* "BOOT" PROGRAM. 

RHKKHK KKK KK KIKI KE IKK KIRK ERE RRR ERE EERE RRR KEKE 


DEF SBOOTP 


SBOOTP DATA >0000 FRAME SIZE 

: DATA >0000 LEXICAL NESTING LEVEL 
DATA >0000 PRIORITY 
DATA >0100 STACK SIZE 
DATA >0000 HEAP SIZE 
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KKKKKKKREKEEKE REE IRE RK KER EERE EERE 


* ADDRESS OF THE "RAM TABLE," THE TABLE THAT DESCRIBES THE 
* REGIONS OF READ-WRITE MEMORY TO BE COLLECTED INTO THE 
* HEAP. 
KE KKKEKKEKKKKKEKE KERRIER EKER KKK 
2 DEF SRAMTB | 

SRAMTB DATA RAMTB 
Ppa rar ri agen Paar ar ere ee ene ee a re ee ae ae ee 


* ADDRESS OF THE DIRECTORY OF I/O SUBSYSTEMS. 

Ste ee Lees hee eee eee ee Aa ee ee ee ee ee ene 
DEF SIODIR 

SIODIR DATA IODIR 

KEKEKEEEEEKEKKKEEKEKEKKKEEEKEEEEKKEKEKKKRK KKK KKK EKER KEK 

* THE FOLLOWING TABLE IS A LIST OF "LENGTH IN BYTES, 

* STARTING ADDRESS" PAIRS THAT DEFINE THE RAM TO BE USED 

* BY THE EXECUTIVE: A WORD OF "0" TERMINATES THE LIST. 

* THE RAM REGIONS MUST BE IN ASCENDING ORDER AND MUST NOT 

* OVERLAP. 

KLERKENERERERL ERS CRETE AEAEEEED REREAD ERAATRERED SSRN AREER RES 

RAMTB DATA >FFFE-LOWHP , LOWHP | 
DATA 0 LIST TERMINATOR 

KK KH KKKK KKH KH KKH HERE KIKEEHKKEEAAKEKEKEAKEEKKEKEKEREKEEEEE 

* THE FOLLOWING TABLE IS A LIST OF "SERVICE DIRECTORY, 

* PORT CONSTANTS" PAIRS THAT DEFINE THE I/O SUBSYSTEM TO 

-* BE INITIALIZED WHEN ROUTINE "DSINIT" IS CALLED; 

* A WORD OF "0" TERMINATES THE LIST. 

KHEKEKKEKKKKKKEKKEKKRKEEEEKERKKKKKKEKKEKEKE KEKE 


IODIR EQU §$ 
* 


REF TO2SSD,TO2$PC 


DATA TO2SSD,TO2SPC TO2 SERVICE DIR. AND PORT CONSTANTS REC. 


REF IPCSSD IPC SERVICE DIRECTORY 
DATA IPCSSD,0 


DATA 0 LIST TERMINATOR 
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HHRKKKHKRKKKEKEKKEEKEKEAEEEEREKKERERKEREREREEREKEREREREEERERRERKEEREKRE 


* THE FOLLOWING IS A PORT CONSTANTS RECORD FOR THE 


* OPERATOR INTERFACE I/0 SUBSYSTEM \ 
KKK RRR KERR KEKKEKKERERKER 





TO2SPC EQU $ 
¥ 


1 ay as 
ee tee hte et 


DATA 0 LINK 
DATA 4 INTERRUPT LEVEL 
DATA >0080 CRU ADDRESS | 
DATA 0 BAUD RATE; 0 => ADJUSTABLE 
DATA 0 HEAP SIZE 7 
DATA 0 INTERFACE HANDLER 
DATA NAMEO PORT NAME ~ | 
DATA LNGTHO PORT NAME LENGTH 
DATA NODE1] NODE HEADER POINTER 
¥ 
NODE] DATA NODE2 LINK 
DATA 0 NODE TYPE 
DATA NAME1 NODE NAME 
DATA LNGTHL NODE NAME LENGTH 
. DATA >8001 OPTIONS = ( ECHO, CR/LF AFTER WRITE ) 
NODE2 DATA 0 LINK 
DATA 0 NODE TYPE 
DATA NAME2 NODE NAME 
DATA LNGTH2 NODE NAME LENGTH 
DATA >AO0O1] OPTIONS = ( ECHO, CR/LF AFTER READ, 
; CR/LF AFTER WRITE ) 
NAMEO TEXT 79902 AT >0807 > 
LNGTHO EQU $-NAMEO a 
| EVEN 
*& 
NAME1 TEXT “OPERATOR 
LNGTH1L EQU S$-NAMEL 
EVEN 
* 
NAME2 TEXT “VpT’ ; 
LNGTH2 EQU $—-NAME2 
EVEN 
END 
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6.4 LINK EDITING 


Link editing enables the user to link together the user application, 
the File I/O Decoder, the desired I/0 Subsystems, and required 
run-time support. The link editor in the user*s development system 


provides the necessary software tools to carry out the configuration 
process. The link editor requires as input a link edit control file. 
The paragraphs that follow describe the link editor and link edit 
control files. 


6.4.1 Link Editor 


For information on initializing and executing the link editor, refer 
to the Model 990 Computer Link Editor Reference Manual (949617-9701) 
Or to the 9900 AMPLUS Software System User”s Manual (MP375). 


6.4.2 Link Edit Control File 


The user must create a link edit control file to input to the Link 
Editor. This file is generated using the text editor and is specified 
when the link editor is brought up. The link edit control file defines 
which modules are to be linked into the load module and in which order 
they are to be linked. 


A sample link edit control file is presented below. Detailed 
information concerning the format and instructions used can be found 


in the user manuals for the respective link editors. 


NOTE: 


The file names used below are merely examples. The actual file 


names used may change depending on their user-assigned locations. 


TASK 
LIBRARY 
INCLUDE 
INCLUDE 
INCLUDE 
SEARCH 
FIND 
FIND 
FIND 
FIND 
FIND 
FIND 
FIND 
END 


SAMPLE 

MPX.RXSLIB 
(RXKERNEL) 
<CONFIG> 


VOL1L.APPL 


MPX .DESOBJ 
MPX .TO2SOBJ 
MPX . IPCSOBJ 
MPX .DSOBJ 

MPX .CSOBJ 

MPX .MPPSOBJ 
MPX . RXSOBJ 
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SAMPLE 


!PROGRAM NAME ‘i 
!RX RANDOM LIBRARY 

IRX KERNEL 

!USER*S CONFIG 

!USER*°S APPLICATION 

!RESOLVE ALL REFERENCES TO HERE 
!ENCODE AND DECODE 

!OPERATOR INTERFACE 
!INTERPROCESS COMMUNICATION 
IFILE I/O DECODER. 

1CHANNEL ROUTINES 

IDATA TYPES FROM MPX OR DIF I/O 
1RX SEQUENTIAL LIBRARY 


LINK EDIT CONTROL FILE 


Tne above example can either be used with a DX or AMPLUS development 


system. 


If AMPLUS is used, the drive location (e.g., DSOl or DS02) 


can be substituted for the volume name. 


creme reer eye etn oe tee ee ee ee ter 





If the user does not place the tables required by an I/O Subsystem 
in the CONFIG module, he must create a separate module to contain 
these records (these records include the Port Constants Records and 
the Node Constants Record, as well as any other required data. 
Should he do this, the user must "Include" the name of this module 
in his Link Edit Control File. | 


NOTE: Both the IPC and TO2 subsystem sequential object libraries 
contain service directories. The names of these service directory 
modules are REF’ed in the example Config (above). These modules will 
be automatically included in the load module when thelink editor 
encounters the appropriate REF in the CONFIG module. | 
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APPENDIX A 
IMPLEMENTING THE OPERATOR INTERFACE I/0 SUBSYSTEM 


A.1l GENERAL 


This section presents a detailed example of the application of the 
tools introduced in this manual. Routines are developed to permit 
interrupt-driven interactions with most terminals that can be 
connected to a 9902 asynchronous communications controller. The 
approach presented in building this subsystem may be adopted by a 
user in the construction of his own subsystem. Subsection A.2 
describes fundamental routines that permits low-level interface to a 
terminal; they manipulate an abstract representation of a terminal 
(a device record) and may be called from and execute within the 
user”’s application process. Subsection A.3 describes an interface 
handler, a separate process that is implemented with the routines of 
Subsection A.2. It executes concurrently with user processes and 
accepts requests for service via message channels. An I/O subsystem 
is constructed around the interface handler in Subsection A.4 to 
Provide a media-independent collection of I/O services. These 
services are based on an abtraction called a file ID and are 
implemented through commands sent to the interface handler. 


The software in this section is discussed in terms of excerpts from 
the source text that is delivered in library MPX.TO2SLIB. 


A.2 INTERFACE VIA EMBEDDED ROUTINES 


This section describes routines with which the user can perform 
direct I/O to a 9902 at the character or logical record level. The 
9902 provides three concurrent functions: transmission and reception 
of a character via a serial interface and interval timing. In this 
application the 9902 will be configured to interrupt the host 9900 
processor whenever one of these functions completes; since the same 
interrupt is used for each function, interrupt demultiplexing must 
be provided. The routines of this package are 


HO2SRATE Initialize the 9902 including optional 
measurement of the transmission rate 


HO2SOPEN Allocate and initialize the device descriptor 
HO2SWAIT Wait for and demultiplex an interrupt 


HO2SIN Read a character 
HO2SOUT Write a character 
HO2SGET ~ Read a logical record 
HO2SPUT Write a logical record 


and will be discussed in the following subsections. 


Access to each 9902 is made through 32 bits of the CRU address 
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space. The input bits that will be used are 


const 
receiver interrupt = 16; 
transmitter interrupt = 
timer interrupt = 19; 


17; 


Fach of these bits is set to one when the corresponding function 
completes. The output bits are 


const 
request to_send on = 16; 
receiver _interrupt_enable = 18; 
transmitter interrupt enable = 
timer _interrupt_enable = 20; 


19; 


"Request to send" is used to activate the transmitter. Writing a 
zero or one to the other bits disables or enables, respectively, 
interrupts at the completion of the corresponding function; in 
either case a pending interrupt is cleared. The eight CRU bits 
beginning at displacement zero are used to move data to and from the 
9902. (More information on the 9902 can be found in the TMS9902 
Asynchronous Communications Controller Data Manual.) 


The interface to a particular 9902 will be represented by the device 
descriptor shown in Figure A-l. Variable BASE contains the CRU base 
of the particular 9902 that is associated with the record; RATE is 
the baud rate at which (both) transmission and reception occur. 
CHARACTER_SENT and TIMER_ELAPSED are flags that are set by the 
interrupt demultiplexer to indicate the completion of the 
corresponding function. KEYBOARD BUFFER, NEXT_IN, NEXT _OUT, and 
NUMBER OF CHARACTERS comprise a Circular buffer into which 
characters are placed as they are received from the 9902; if the 
buffer is full when a character arrives, the flag CHARACTER_LOST is 
set. ATTENTION is the semaphore to which the 9902 interrupt is 
connected. 


const 
Circular buffer size = 16; 


type 
device 9902 = record 
base, rate: integer; 3 
character sent, timer elapsed: boolean; 
character _lost: boolean; 
attention: semaphore; 
keyboard buffer: 

Packed array [ 1..circular_buffer size ] of char; 
next_in, next_out, number of characters: integer; 
end: 

device ptr = @device 9902; 


FIGURE A-l. 9902 DEVICE DESCRIPTOR 








A.2.1 Procedure HO2SRATE 
This procedure has calling sequence 
procedure h02Srate ( base: integer; var rate: integer ) 


and is used to initialize the 9902 at CRU base BASE. If RATE is 

zero and has an acceptable value (110, 300, 600, 1200, 2400, aB00, 
9600, or 19200 baud), then both the transmitter and receiver. are 
initialized for that communication rate. Otherwise, the start bit of 
the first character that is entered is timed, and the transmission 
rate is calculated: the least significant bit of the first character 
must be "1" (e.g., a carriage return). The interval timer is set to 
16.32 milliseconds. 


A.2.2 Procedure HO2SOPEN 


The first routine in this package that is called must be HO2SOPEN 
(Figure A-2), the routine that initializes the 9902 interface. The 
device record for the 9902 is allocated and initialized. The 
parameter LEVEL is used to associate the semaphore ATTENTION with 
the appropriate interrupt level and enable that interrupt through a 
TMS9901 programmable systems interface (which is assumed to be at 
eld a #0100, as is the case for the TM990 family of computer 
oards). 








tne eee ie Shee ee ee 8 le 


procedure h02Sopen ( base, lievel: rate: integer; 
var d: device ptr ); 
const 
base 9901 = #100; 
begin z 
new( d ); : ee 
with dv = d@ do begin 
dv.base := base; 
hO2Srate( base, rate ); 
dv.rate := rate; 
dv.character sent := true; 
dv.timer_ elapsed := false; 
dv.character _lost := false; 
initsemaphore ( dv.attention, 0 ); 
externalevent( dv.attention, level ); 
dv.next_in := l; 
dv.next out s= 1; 
_dv.number of characters := 0; 
_ Crubase( base 9901 ); 
sbz( 0 ); 
crubase( base 9901 + 2*level ); 
sbo( 0 ); 
crubase( base ); 
sbo( receiver_interrupt_enable ); 
end; 
end { h02Sopen |}; 


FIGURE A-2. PROCEDURE HO2SOPEN > 


A.2.3 Procedure HO2SWAIT 


This procedure (Figure A-3) waits until an interrupt is generated by 
the 9902 which is specified by the device record that is its 
Parameter. The CRU bits TRANSMITTER __INTERRUPT, RECEIVER INTERRUPT, 
and TIMER_INTERRUPT are examined to determine which interrupts have 
occurred. The response for transmitter and timer interrupts is to 
clear the interrupt and set the appropriate flag to be examined by 
the caller of HO2SWAIT. If a receiver interrupt occurs, a character 


is read from the 9902 and stored in the keyboard buffer; 


NUMBER_OF_ CHARACTERS is incremented to indicate that keyboard 
characters are available. (The keyboard is buffered so characters 
can be entered while output is taking place.) 











procedure hO02Swait( d: device ptr ); 
var 
ch: char; 
begin 
with d@ do begin 
crubase( base ); 
Wait( attention ); 
if tb( transmitter interrupt ) then begin 
sbz( transmitter _ _interrupt_enable ); 
character sent := true; 
end; 
if tb( receiver_interrupt ) then begin 
sbz( receiver _interrupt_ enable ); 
if number of _characters < circular buffer. _size then begin 
stcr( 8, ch::integer ); 
keyboard buffer [ next_in ] := ch; 
if next_in = circular _buffer_size then 
next _ in := 0; 
next _ in := next_in + l; 
number of characters := number _of characters + 1; 
end 
else 
Character lost := true; 
sbo( receiver_interrupt_enable ); 
end; 
if tb( timer_interrupt ) then begin 
sbz( timer interrupt enable ); 
timer _elapsed 2= true; 
end; 


end; 
end { h02Swait }; 
FIGURE A-3. PROCEDURE HO2SWAIT 


A.2.4 Procedure HO2SIN 


This function (Figure A-4) returns the next character from the 
keyboard buffer. Note that HO2SWAIT is called if 


NUMBER _OF CHARACTERS iS zero since the calling program must wait | 


until a character arrives. 


function h02$in( d: Bevace Pee ): char ; 
begin 
with d@ do begin 
while number of characters = 0 do 
hO2Swait( d )>; 
h0O2Sin := keyboard buffer[ next _out 1; 
if next_out = circular _buffer _size then 
next _out <= OQ; | 

next out := next _out + Il; 
number _of _characters := number _of _characters - l; 
end: 

end { h02Sin }; 


Figure A-4. PROCEDURE H02SIN 


A.2.5 Procedure HO2SOUT 


This procedure (Figure A-5) sends a character to 9902 for 
transmission. If the transmission of the last character has not 
completed, HO2SWAIT is called until the . TRANSMITTER INTERRUPT 
occurs. After the character has been sent to the 9902, the 
transmission rate is examined. If it is 1200 baud, the output device 
is assumed to be a mechanical printer and delays are inserted to 
compensate for movement of the print mechanism of a TI Model 733 
terminal. That is, characters are accepted at 1290 baud but printed 
at 300 baud; a .carriage return requires as much time as 23 
characters at 1200 baud. If the transmission rate is less than 1200 
baud, then a delay is inserted only for a carriage return. Thus the 
delavs per carriage return and per 1200 baud character are _ the 
number of 16.32 millisecond intervals required to transmit 23 and 3 
characters, respectively, at 1200 baud. (Note that, since the 
interval timer is free-running, the delay loop begins at 0, not l, 
to ensure that the proper number of full intervals is delayed.) 











const 
delay per_cr 12; | 
23 char. delay per cr at 1200 baud 
* 10 bits per character 
div 1200 bits per sec 
div .01632 seconds per interval 
_ + 1 to round up 


delay per 1200 _baud_character 23 


e * 10 bits per character 
a : div 1200 bits per second 


. div .01632 seconds per interval 


_ | + 1 to round up 


procedure h02Sout( d: device_ptr; ch: char ); 
var 
delay: integer; 
begin 
with d@ do begin 
crubase( base ); 
while not character_sent do 
hoO2$Swait( d ); | 
Character _sent := false; 
sbo( request_to_send_on ); 
ldcr( 8, ch:sinteger ); | 
sbz( request_to_send_on ); 
sbo( transmitter _interrupt_enable ); 
if rate <= 1200 then 
delay block: begin 
| if ch = cr then 
delay := delay per _cr 
else 7 
if rate = 1200 then 
delay := delay per _ 1200 baud character 
else escape delay block; 
while not character _sent do 
hO2$wait( d ); 
for i := 0 to delay do begin 
sbo( timer_interrupt_enable ); 
while not timer_elapsed do 
h02Swait( d ); 
timer elapsed := false; 
end; 
end; 
end; — | 
end { h02Sout }; 


FIGURE A-5.- PROCEDURE HO2SOUT 


A.2.6 Procedure HO2SGET 


This procedure (Figure A-6) permits a logical record (terminated by 
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3 char. delay per 1200 baud char. 


a carriage return) to be read from the 9902. The option parameter 
OPTIONS controls whether the record will be echoed as it is entered 
and whether a carriage return / line feed sequence will be emitted 
before the record, after the record, or not at all. If the first 
character that is entered is a DC3 (control-S), then "-1" is 
returned as the number of characters read (COUNT) to indicate that 
end-of-file has occurred. Otherwise, up to MAX LENGTH characters are 
read into the buffer B. The back ‘space (control-H) may be used to 
edit a line as it is entered. 


type 
option_record = packed record 

echo | - while “reading: boolean; 
cr _lf _before read: boolean; 
cr lf after _read: boolean; 
cr _1f before _write: boolean; 
cr lf after write: boolean; 
end; 


procedure h02$get( d: device _ptr; b: dummy_buffer_ptr; 
max length: integer; 
options: option record; 
var count: integer ); 


FIGURE A-6. PROCEDURE HO2SGET (SHEET 1 OF 2) 


var 
ch: char; 
is integer; 
echo: boolean; 
begin 
with d@ do begin 
ch := hO2Sin( d ); 
if ch = dc3 then count := -l 
else begin 
echo := options.echo while reading; 
if echo and options.cr_1f before_read then begin 
hO2Sout( d, cr ); 
hO2Sout( d, lf ); 
end; 
i := 0; 
loop: while true do begin 
i:=i+1; 
if ch = bs then begin | 
if echo then hO2Sout( d, 1f ):; 
repeat 
if i > 1 then begin 
is=i- 41; 
if echo then h0O2Sout( d, bs ); 


end; 
ch := hO2Sin( d ); 
until ch <> bs; 
end; 
if ch = cr then begin 
count := i-1l; 
escape loop; 
end 
else begin 
if echo then hO2Sout( d, ch ); 
b@[ i ] := ch; 
if i < max_length then ch := h02Sin(d ) 
else begin 
count := i; 
escape loop; 
end; 
end; 
end; 
if echo and options.cr_ 1f after_read then begin 
hO2Sout( d, cr );3 ~ ~~ 
h02Sout( d, 1f ):;3 
end; 
end; 
end; . 
end { h02$get |}; 


FIGURE A-6. PROCEDURE HO2SGET (SHEET 2 of 2) 
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A.2.7 Procedure HO2$PUT 


This procedure (Figure A-7) writes a record to the 9902 interface 
with carriage control as specified by the option parameter OPTIONS. 


procedure hO2Sput( d: device _ptr; bs: dummy _buffer_ptr; 
count: integer; options: option_record ); 
var 
cmd: command_ptr; 
begin 
with d@ do begin 
if options.cr_1f before write then begin . 
hO2Sout( d, cr ); 
h02Sout ( d, lf ); 
end; 
for i := 1 to count do 
hO2Sout( d, b@[ i ] );3 
if options.cr _1f after write then ore 
hO2Sout( d, cr ); | 
hO2Sout( d, lf ): 
end; 
end; 
end { h02Sput }; 


FIGURE A-7. PROCEDURE HO2SPUT 


A.2.8 An Example 


Figure A-8 shows the skeleton of an operator communications program 
that communicates with the user by reading a command from the same 
line on which a prompt has been written. The 9902 is configured for 


the primary port of a TM990/101 board with CRU base of #080 and 


interrupt level 4; the interface routines will measure _ the 


transmission rate. Note that the operator program must have a. 


Priority that is consistent with the interrupt level of the 9902 
Since the program will be waiting on an interrupt semaphore. 


A-10 











system example; 


type 
buffer = packed array[ 1..80 ] of enar 
buffer ptr = @buffer; | 


device ptr = @device ptr; 


option_record = packed record 
echo while reading: boolean; 
cr 1f _before_ read: boolean; 
cr _1f after read: boolean; 
cr _lf _ before _write: boolean; 
cr _lf _after _write: boolean; 
end; 


procedure h02Sopen( base, level, rate: integer; 
var d: device ptr ); .- 
external; 
procedure h02$get( d: device ptr; b: buffer ptr; 
| max_length: integer; 
options: option record; 
var count: integer ); 
external; 
procedure h02$put( d: device_ptr; b: buffer_ptc; 
count: integer; options: option_ record ); 
external; 


FIGURE A-8 AN EXAMPLE (SHEET 1 OF 2) 
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program operator; 
var 
d: device_ptr; 
count: integer; 
input_buffer, output buffer: nahin wes 
options: option_ record; 
begin 7 
{# priority = 4 
hO2Sopen( #080, 4, 0, d ); 
new( input buffer ); 
new( output_buffer ); 
with options do begin 
echo while reading := true; 
cr. _1£ _before _read := false; 
Cr a _after _read s= false; 
cr lf before _write := true; 
cr lf after write := false; 
end; 
while true do begin 
Fill the output buffer with a prompt. } 
hoO2Sput( d, output buffer, 80, options ); 
h02Sget( d, input buffer, 80, options, count ); 
Process the command in input buffer. 
end; 
end { operator Is 


ic 


end { example }. 
FIGURE A-8. AN EXAMPLE (SHEET 2 OF 2) 


A.3 INTERFACE VIA MESSAGE CHANNELS 


The previous section presents routines that may be executed within 
the user’s process to communicate with a serial-device. The primary 
advantage of this level of interface is that there is a minimum data 
space overhead. It is particularly appropriate for applications that 


have a single user process. If several processes require access to a 


device, it is desirable to produce an interface handler, a process 
that services a queue of requests from application processes and 
communicates with the device that it controls. With this approach it 


ls possible for application. processes to overlap -computation with 
input and output. 


Figure A-9 shows HO2SHANDLER, an interface handler constructed from 
the routines described in Subsection A.2. BASE, LEVEL, and RATE are 
parameters to HO2SHANDLER which are required by HO2SOPEN' to 
initialize a 9902. KEYBOARD and PRINTER are message channels upon 
which input and output requests, respectively, will arrive. Each 
request to the handler is a record of type COMMAND. BUFF is a 
pointer to a buffer of size LENGTH characters. COUNT is set by the 
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user to indicate the number of characters to be sent and is set by 
the handler to indicate the number of characters received. OPTIONS 
is the option record described in Section A.2.6. 


The calls to the routine CSNOTIFY cause the device interrupt 
semaphore to be signaled whenever a command is sent to the KEYBOARD 
Or PRINTER channel, thus simulating an interrupt. Note that the code 
for HO2SWAIT in Section A.2.3 waits for any signal to ATTENTION, 
whether it be generated by an interrupt or by a software signal. The 
processing in the handler occurs within an infinite loop that is 
traversed whenever there is a state change (signal to ATTENTION). If 
a keyboard or printer command is not pending, CSCRECEIVE is’ called 
to accept a command if one has arrived. If a character has been 
entered (the keyboard buffer is not empty) and a keyboard command is 


present, the HO2SGET is called to input a logical record, and 


CSACKNOWLEDGE is called to signal the requestor that his command has 
been processed. If there is no _ keyboard activity and a printer 
command is present, then HO2SPUT is called to output a record. If 
neither keyboard nor printer activity is pending, HO2SWAIT is called 
to await a change of state. 


Note that a printer command is not peoceasee unless there is no 
keyboard activity pending. If a series of printer commands is queued 
for output and a character is entered at the keyboard, printer 
activity will be suppended at the end of the current record until 
the keyboard record has been completely entered. Since HO2SGET is 
not called unless the printer is idle, there is no _ need to 
synchronize access to the printer in order to echo keyboard 
characters. With this implementation characters will not be echoed 
unless a keyboard request is pending. Note also that HO2SWAIT is not 
called following the processing of a keyboard or printer command 
unless all tests for pending activity fail. These tests must all be 
made since it is possible that a change of state (e.g., arrival of a 
keyboard command) occurred when HO2SWAIT had been called by a 
routine (e.g., HO2SOUT) that could not recognize the simulus. 


type 
command = record 
buff: dummy _buffer_ptr; 
length, count: integer; 
options: option_record; 
end; 
command ptr = @command; 


program h0O2Shandler( base, level, rate: integer; - 
keyboard, printer: cid ); 
var 
d: device ptr; 
keyboard cmd, printer_cmd: éommand: pecs 
begin 
{# stacksize = 100; priority = level } 
h0O2Sopen( base, level, rate, d ); 
with d@ do begin 
' keyboard_cmd := nil; 
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printer cmd := nil; 
cSnotify( keyboard, attention ee 
cSnotify( printer, attention ): 
while true do begin 
if keyboard cmd = nil then 
cS$creceive( keyboard, keyboard. cmd ); 
if printer_cmd = nil then 
c$creceive( printer, printer _cmd ); 


if number of characters > 0 and keyboard cmd <> nil then begin 


hO02$get( d, keyboard cmd@.buff, keyboard cmd@.length, 
keyboard. cmd@.options, keyboard | ~emd@.count ); 
cSacknowledge( keyboard cmd ); = s 
keyboard cmd := nil; 
end 
else 
if printer _cmd <> nil then Begin 
hO2Sput( d, printer cmd@.buff, printer _cmdé@. count, 
printer _emd@. options ); 
cSacknowledge( printer cmd ); 
printer cmd := nil; 
end 
else hO2Swait(d ); 
end; 
end; 
end { h02Shandler }; 


Figure A-9. AN INTERFACE HANDLER 


A.4 INTERFACE VIA FILE I/O SUBSYSTEM 


In this section a file I/O subsystem conforming to the conventions 
of Section 6.3 is constructed that permits media-independent 
communication with the interface handler HO2SHANDLER that was 
described in Section 7.3. Of the services that must be provided by 
an I/O subsystem (Subsection 2.4.2), only INIT, CONNECT, READ, 
WRITE, WAIT, and DISCONNECT require special versions; the remaining 
services are provided by entries of the "dummy" subsystem 


(documented in Appendix D). 


Figure A-10 presents the data structures that are device dependent. 
The command record is the same as that described in Subsection A.3. 
TO2SFID VARIABLES RECORD contains. the variable data that are 
associated with each file that is connected to the subsystem. 
COMMAND is a pointer to the command record that is used to request 
services for the file. READ LENGTH PTR is used to remember the 
address of the parameter ACTUAL LENGTH “that must be set when a_ read 
request completes. OPTIONS contains the formatting options for the 
File (Subsection A.2.6). TO2SNODE HEADER_RECORD specifies one 
pathname that will be serviced by this subsystem and the format 
options for that file. TO2SPORT_ CONSTANTS RECORD is standard with 
the exception of the usage of the I/O address double word; in this 
application it contains the CRU base and transmission rate of the 
port. The two fields in TO2$PORT VARIABLES RECORD contain the 
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message channel IDs of the keyboard and printer (input and output 
devices) of the port.. (Computing WAITING as #7FFF + 1 yields a 
one-word constant with value #8000; entering #8000 directly results 
in a LONGINT constant.) 


const 
ok = #0000; 
waiting = #7FFF + 1 { = #8000 }; 


t Grae 


type | 

command record = packed record 
buffer: dummy_buffer_ptr; 
length: integer; 
count: integer; 
options: option_record; 
end; 

command ptr = @command_record; 


t02$fid variables record = record 
subsystem dependent structure } 
command: command_ptr; 
read_length ptr: @integer; 
options: option_record; 
end; 


t02Snode_header_record = record 
link: node_header_ptr; 
node _ type: integer; 
node_name: dummy buffer ptr; 
node_name_ length: integer; 
{ subsystem dependent fields } 
options: option_record; 
end: 


t02Sport_constants_ record = record 
link: port _constants_ptr; 
interrupt level: integer; 
base, rates: integer; 
heap size: integer; 
interface handler: address; 
port_name: dummy buffer ptr; 
port _name_ length: integer; 
node header: ‘node_header_ptr; 
{ subsystem dependent fields } 
end; 


t02$port_variables_ record = record 
{ subsystem dependent structure 
keyboard: cid; 
printer: cid; 
end; 


FIGURE A-10. SUBSYSTEM DEPENDENT DATA TYPES 
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a.4.1 Procedure TO2SINIT 


This procedure (Figure A-1l) initializes the 9902 terminal 
subsystem. The port variable record is allocated from the heap and 
is initialized with (unique) channel IDs for the keyboard and 
printer devices. The interface handler program HO2SHANDLER is 
activated using parameters from the port constants record. 


procedure t02Sinit{ serv: service directory ptr; 
port_cons: port _constants,ptr; 
var sub: -subsystem_ptr |; 
var 
port_vars: port variables ptr; 
begin 


new( port vars ); 
with port_ ~vars@ do begin { initialize port variables } 
cSinit( 0, keyboard ); 
cSinit ( 0, printer ); 
Start hO2Shandler( port _cons@.base, | 
port_ ~cons@. interrupt level, 
port | ~cons@.rate, 
keyboard, 
printer ); 
end; 7 
dSsubsystem( serv, port cons, port vars, sub )s 
end { t02Sinit }; 


FIGURE A-11l. PROCEDURE TO2SINIT 


A.4.2 Procedure TO2SCONNECT 


This procedure (Figure A-12) is called to determine if a pathname 
corresponds to a node of this subsystem; utility function EQSNAMES 
is used to compare pathnames with node names. If the pathname is 
recognized, then a file ID variable record is created, and DSFID is 
called to allocate and initialize a file ID. record. 
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procedure t02$connect { sub: subsystem ptr; 
var pathname: dummy buffer; 
length: integer; 
var £: fid |; 
var 
found: boolean; 
node: node_header _ptr; 
fid_ vars: fid variables ptr; 


Function eqSnames( var pathnamel: dummy_buffer; lengthl: integer; 
pathname2: dummy __ buffer _ptr; length2: integer ): 


boolean; external; 


begin 
node := sub@.port_constants@.node_header; 
search: 
repeat 
found := eqSnames( pathname, length, 
node@.node_name, | 
node@.node | _name_length ys 
if found then escape search 
else node := node@.link; 
until node = nil; 
if found then begin 
new( fid_vars ); 
with fid _vars@ do begin { initialize fid vars } 
cSallocate ( size (command_record) , command ); _ 
read length ptr := nil; 
options := node@.options; 
end; 
dSfid ( sub, fid _vars, £ d; 
F@.status := ok; 
f@.state := closed; 
end 
else £— := nil; 
end { t02Sconnect }; 


FIGURE A-12. PROCEDURE TO2SCONNECT 


A.4.3 Procedure TO2SREAD 


- This procedure (Figure A-13) initiates input from the 9902 by 
sending a keyboard command to the interface handler. Since this 


procedure does not wait for the input to complete, the address of 
ACTUAL LENGTH is saved in the FID variable record so the result can 


be returned by TO2SWAIT. 
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procedure t02Sread{ ts fid; 
| bs dummy buffer ptr; 
max length: integer; 
var actual length: integer hs 
begin 
if dSvalid( f, S$read ) then begin 
with vars = f£@.fid variables@, cmd = vars.command@ do begin 
cmd.buffer := b; 
cmd.length := max_length; 
cmd.count := 0; 
cmd.options := vars.options; 


cS$send( f@.subsystem@.port_variables@.keyboard, vars.command ); 


vars.read _length_ptr::address := location( actual_length ); 
F@.status := waiting; 
end; 
end; 
end { t02Sread }; 


Figure A-13. PROCEDURE TO2SREAD 


A.4.4 Procedure TO2SWRITE 


This procedure (Figure 7-14) initiates output to the 9902 by sending 
a printer command to the interface handler. 


procedure t02$write{ f: fid; 
be dummy sbugeen pte 
length: integer }; 
begin 
if dSvalid( £, Swrite ) then begin : 
with vars = f@.fid _variables@, cmd = vars.command@ do begin 
cmd.buffer := Db; 
cmd.length := 80; 
cmd.count := fengene 
cmd.options := vars.options; 


cSsend( f@.subsystem@.port variables@. printer, vars. ecnmand ); 


vars.read_ length ptr := nil; 
F@.status := waiting; 
end; | 
end; 
end { t02$write }; 


FIGURE A-14. PROCEDURE TO2SWRITE 


A.4.5 Procedure TO2SWAIT 


This procedure (Figure A-15) waits for a keyboard or printer request 
to be completed. If READ LENGTH PTR is not NIL, then the command was 


to the keyboard, and the number of characters that were transferred 
is returned as the result ACTUAL _LENTGH of T2SREAD. 
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procedure t02Swait{ f: fid }; 
begin 
if £@.status < ok then 
with £@.fid_variables@ do begin 

cSwait( command ); 

f@.status := ok; 

if read_length ptr <> nil then begin 

if command@.count < 0 then f@.status := eof_encountered; 


read_length ptr@ := command@.count; 
read _length_ptr := nil; 
end; 

end; 


end { t02Swait }; 


FIGURE A-15. PROCEDURE TO2SWAIT 


A.4.6 Procedure TO2SDISCONNECT 


This procedure (Figure A-16) disconnects a file ID by deallocating 
the command and file ID varaiables records and calling DSRELEASE the 
release the file ID record. 


procedure t02$disconnect{ var f: fid ls 
begin 
if dSvalid( £, Sdisconnect ) then begin 
cSdispose( f@.fid_ variables@.command ); 
dispose( £@.fid_ variables ); 
aSfidrelease( f£ ); 
end; 
end { t02Sdisconnect }; 


FIGURE A-16. PROCEDURE TO2SDISCONNECT 


A.4.7 Module TO2S$SD 


This module (Figure A-17) declares the service directory for the 
9902 terminal interface subsystem. Services OPEN, CLOSE, DSTATUS, 
ABORTIO, CREATE, DELETE, and POSITION are provided by the "dummy" 
subsystem (Appendix D). 


REF TO2SIN,T02$CO,DUMSOP,TO2SRE,TO2$WR,DUMSCL 
REF DUMSDS,TO2SDI ,DUMSAB,DUMSCR,DUMSDE,DUMS$PO,T0O2$WA 


TO2SSD EQU S$ 7 KKKKKENTRY kRKKK 


DEF TO2SSD 
* 


DATA DIRSZ,TO2SIN,T02SCO,DUMSOP,TO2SRE,T0O2SWR,DUMSCL 
DATA DUMSDS,TO2SDI , DUMSAB , DUMSCR, DUMSDE, DUMSPO, TO2SWA 


. FIGURE A-17. MODULE TO2SSD 
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A.4.8 Module TO2SPC 


This module (Figure A-18) is a sample port constants structure for 
the 9902 subsystem. The port is the primary 9902 on a TM990/101 
board (CRU base >0080 and interrupt level 4) and the transmission 
rate will be determined by the first character received. Two nodes 
are provided, OPERATOR and VDT; they differ only with respect to the 
Carriage control options: OPERATOR permits a prompt to be written to 
the line from which keyboard input will be read. (OPERATOR is’ the 
node to which the default ghost vrocedure directs the output of the 
Standard procedure MESSAGE.) 


TO2SPC EQU $ KRRKEENTRY * KEKE 
DEF TO2SPC 
* 
DATA 0 LINK 
DATA 4 INTERRUPT LEVEL 
DATA >0080 CRU ADDRESS 
DATA 0 BAUD RATE: 0 => ADJUSTABLE 
DATA 0 HEAP SIZE (CURRENTLY UNUSED) 
DATA 0 INTERFACE HANDLER 
DATA NAMEO PORT NAME 
DATA LNGTHO PORT NAME LENGTH 
. DATA NODEL NODE HEADER POINTER. CANNOT BE NIL. 
NODE1L DATA NODE2 LINK , 
DATA 0 NODE TYPE 
DATA NAMEL NODE NAME 
DATA LNGTH1 NODE NAME LENGTH 
: DATA >9000 OPTIONS = ( ECHO, CR/LF BEFORE WRITE ) 
NODE2 DATA 0 LINK 
DATA 0 NODE TYPE 
DATA NAME2 NODE NAME | 
DATA LNGTH2 NODE NAME LENGTH 
DATA >D0QO OPTIONS = ( ECHO, CR/LF BEFORE READ, 
J | CR/LF BEFORE WRITE ) 
* 
NAMEO TEXT 79902 AT >0807 
LNGTHO EQU $-NAMEO 
EVEN 
* 
NAME]L TEXT “OPERATOR” 
LNGTH1 EQU S-NAMEL 
EVEN 
* 
NAME2 TEXT “VDT” 
LNGTH2 EQU S—NAME2 
| EVEN : 


FIGURE A-18. MODULE TO2SPC 
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. APPENDIX B 
INITIALIZATION DATA STRUCTURES 


B.1 GENERAL 


The information that follows presents the data structures included in 
the configuration of systems with I/O Subsystem components and used in 
their initialization. Also presented in this appendix are those data 
structures associated with the IPC Subsystem described in Section IV. 


Prior to presenting this material, the requirements affecting the way 
in which initialization must work are listed. 


B.2 INITIALIZATION REQUIRMENTS 


Listed below are the Device Independent File I/O initialization 
requirements. These requirements affect the data structures used by 
the device independent file I/O. routines. 


e I/O Subsystems are members of TI”“s family of component 
software (see Subsection 1.4 for a description of TI 
component software). As such, they may not be bound to a 
Specific system configuration until power up. Therefore 
the data structures that define the system configuration 
must be part of the initialization code. 


@ The call to system initialization can occur at any of the 
various levels of entry into the I/0 model (File I/O 
Decoder level, I/O Subsystem level, interface handler 
level). Therefore, the data must be structured into 
hierarchical levels. 


@e Many users will require the configuration code to be 

- specified in ROM. Therefore, the data must be partitioned 

into ROM (for constant and default values), and RAM (for 
variable or dynamic values). 


B.3 INITIALIZATION DATA STRUCTURES 


The data structures required for system initialization are described 
in the subsections that follow. These data structures are constructed 


and organized to meet the initialization requirments listed above in 
Subsection B.2. 


B.3.1 I/0 Service Directory (DSIODIR). 


-~ The 1/0 Service Directory (DSIODIR) is the top-level data structure 


\... required for system initialization. This directory contains a two-word 
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entry for each of the I/O Subsystems in the target system that can be 


accessed via the File I/O Decoder. The end of this directory is marked ~~" 


by a null entry. 


Each word in the two-word entry contains a pointer to a data structure 
containing information required by its associated I/O Subsystem. The 
first word points to the service directory for the I/O Subsystem. The 
second word points to a Port Constants Record (for the first I/O port 
managed by that subsystem). Information on these data structures is 
presented in Subsections B.3.2 and B.3.3 respectively. 


Figure B-l depicts the I/O Service Directory. 


#00 
IOSVCDIR@ 
#02 Entry for First I/O 
<i PORTCONS@ Subsystem on Target 
ITOSVCDIR@ 
#06 Entry for SECOND I/O 
eae PORTCONS@ Subsystem on Target 


Remaining I/O Subsystems 
on Target 





Null entry marking 
End of table’ 


FIGURE B-l. I/O SERVICE DIRECTORY 


B.3.2 I/0 Subsystem Service Directory (IOSVCDR). 


As stated above, the first word in each of the two-word entries making 


up the I/O Service Directory is a pointer to the I/O Subsystem Service 
Directory (IOSVCDR). The I/O Subsystem Service Directory contains the 
entry points to the specific procedures within the I/O Subsystem which 
must be invoked to perform the file level services requested via the 
File I/O Decoder (i.e., via calls to the DSroutines listed in 
Subsection 2.3.1). As previously stated, these I/O Subsystem entry 
points are formed by attaching a prefix (unique to the particular 
subsystem) to the generic names of the file services (connect, open, 
read, write, etc.). | 


The 1/0 Subsystem Service Directory is normally packaged in one of the 
libraries supplied with an I/O Subsystem. The directory itself is 
pulled into the load module at link ;edit ;time 


The first entry in the I/O Subsystem Service Directory specifies the 


B-2 


eee 




















length of the directory. This entry is required because the user has 
the capability of adding additional entry points as warrented by the 
I/O Subsystem. | 


Figure B-2 depicts the I/O Subsystem Service Directory. The entries 
listed below are the minimum entries that each such directory must 
contain. (As noted previously, even if a particular I/O Subsystem does 
not contain a procedure to implement a file level service requested 
Via the File I/0 Decoder, it still contains a corresponding entry 
point. However, in this case, the entry point iS associated with a 
dummy routine. Note that the order of the entry points in the table is 
ae and specified by the I/O standards, as shown in the figure 
elow. 





#00 
#02 
#04 
#06 
#08 
#0A 
#0C 
#0E 
#10 
#12 
#14 
#16 
#18 


#1A 


























FIGURE B-2. 
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of this record ( Currently 


XxXxSinit routine 


xxxSconnect routine 


XxxxSopen routine 


xxxSread routine 


xxxSwrite routine 


xxxSclose routine 


xxxSdstatus routine 
xxxSdisconnect routine 
xxx$abortio routine 
xxxScreate routine 
xxxSdelete routine 
XXxXSposition routine 


XXxXSwait routine 


I/O SUBSYSTEM SERVICE DIRECTORY 


not 


ae 


 B.3.3 Port Constant Record (PORTCONS) 


fhe second word in each two-word entry contained in the I/0 Service 
Directory contains a pointer to a Port Contstants Record (PORTCONS). A 
Port Constants Record contains constant information describing the 
physical characteristics of an I/O port associated with a given I/0 
Subsystem (port refers to the connection between the system and the 
-I/O device or node). The Port Constants Record may contain only fixed 
information because in many cases, Port Constant information will be 
accessed from read-only memory during normal program execution. The 
user can build his Port Constants Record in the CONFIG module or can 
place it in a separate module. If he chooses the latter, the user will 
have to "include" this module in his link edit control file. 


More than one port may be accessible to an I/O Subsystem; a _ separate 
Port Constants Record exists for each port. All the Port Constant 
Records associated with a single subystem are joined together in a 
forward linked list. The pointer present in the I/O Directory begins 
the list. Each Port Constants Record in turn points to the Port 
Constants Record for another associated Port. The last Port Constants 
Record in the list contains a null pointer. 


The required format of the Port Constants Record is displayed below in 
Figure B-3 (note that the last part of this structure is reserved for 
I/O Subsystem-dependent information). 





tie ee ee ee ee 


#00 


#02 


#04 


#06 


#08 


#0A 


#0C 


#0E 


#10 


#12 






Pointer to next port constants record 





Indicates the interrupt level of a device 


interrupt level 
eanaek 


Port address 1 (used when appropriate to 
specify a memory mapped I/O port) 


Port address 2 (used when appropriate to 
specify a memory mapped I/O port) 


length 


node constant 
record pointer 


FIGURE B-3. PORT CONSTANTS RECORD 


Size of the heap packet allocated to the 
subsystem (may be nil) P 





Address of interface handler (must be 
specified) , | 


Address of the string containing the port’s 
name (may be undefined) 


Length of the port’s name (may be 0) 


Pointer to the associated Node Constants. 
Record (may be nil) 





Subsystem dependent fields 
e.g. Baud Rates, etc. 


B.3.4 Node Constants Record 


The Node Constants Record (also called Node Header Record) provides a 
Gesciption of a terminal node accessible through a port. In essence, 
node refers to the actual physical device (contrast with file which is 
a logical entity). Each terminal node accessible through the port has 
a separate Node Constants Record associated with it. A forward link 
list connects all of the Node Constants Records associated with a 
given port. 


The format of the Node Header Record is presented below in Figure B-4. 
As for the Port Tonstants Record, the Node Constants Record must 
contain only fixed information. As such, the user should build this 
record in ROM. 


#00 , 3 
link Points to the next node header record 


#02 
node type Indicates the type of the node 

(currently not used) 

#04 
node name Pointer to the string containing the nodes 

name (must be specified) | 

#06 
node name Length of the node’“s name (cannot be 0) 
length | 

#08 

Subsystem dependent fields 





FIGURE B-4. NODE CONSTANTS RECORD 


B.3.5 File Identification Record (FIDRCD). 


When an I/O Subsystem begins execution, it calls a procedure to 
allocate memory for and link in a File Identification Record (FIDRCD). 
The File Identification Record thus created provides for the 
association of a file (passed to the I/O Subsystem by the Connect 
Procedures) with the device controlled by that I/O Subsystem. In 
addition, The FIDRCD provides for the return of I/O "Status" and file 
"State" information and associates the specific user with the specific 
file. Subsegeunt to the "Connect", the FIDRCD is used to identify the 
file being manipulated to the I/O Subsystem. All FIDRCDs associated 
with a single process are connected in a forward link list. The 
pointer on the last FIDRCD is set to nil. The format of the FIDRCD is 
fixed as displayed below in Figure B-5. 





#00 | 7 
Pointer to next FID in the linked list 


Global frame 


FIGURE B-5. FILE IDENTIFICATION RECORD 


#02 








Pointer to the subsystem record 
associated with the file 

#04 
Status of the file 


#06 
State of the file 


#08 
Pointer to the subsystem dependent 
variable record (FID Variables Record) 
#0A 
Address of the global frame of the 
process in which this file identifier 
Was created 

#0C 


B.4 IPC I/O SUBSYSTEM DATA STRUCTURES 


These data structures are used exclusively to implement’ the 
interprocess communication (IPC) I/O subsystem. The following data 
Structures allow data to be transferred via messages passed through 
channels. 
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-B.4.1 IPC FID Variables Record 


fhis record iS accessed through a FID record. It contains the 
addresses of parameters used to read data, the file”s message buffer, 
and a pointer to the pathname record. 







#00 : 
Address of the word into which the 
number of characters transferred 
is to be stored at the completion 
of a read request 


read length 
pointer 


maximum 
length 
read 
buffer 
pathname 
node 


FIGURE B-7. IPC FID VARIABLES RECORD 


#02 
| Indicates the maximum number of characters 
that can be read into a buffer 
#04 


Address of the buffer into which 
data are to be read 
#06 


Address of the unique pathname record for 
the file 
«#08 


Address of the message record 
used to transmit data 
#0A 


B.4.2 IPC Port Variables Record 


This record is accessed through an IPC-subsystem record. It points to 
a linked list of pathname records, each containing the unique 
Characteristics of a particular file. 


a) 
pathname node 


FIGURE B-8. IPC PORT VARIABLES RECORD 


#00 | 
Address of the semaphore used to ensure 
mutual exclusion when accessing the list 





#02 





Address of the first pathname in the list 
#04 | 
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This record is accessed through either the pathname node field of e— 
IPC FID variable record or the IPC port variables record. TY... 


process oe 
Also’ 


Pathname record contains characteristics unique to a given file. 
contained 


4.3 Pathname Record 


are values 


file”s channel. 


#00 


-_ | 
_— | 
| 
| 
aa: 3 


end of | 
production 


#02 





#04 






#06 






#08 






#OA 






#0C 













Create called 
end of 

consumption 
waiting 

for create 
number of 
producers 
number of 
consumers 

number connected 

Channel 


#0E 
#10 


#12 






#14 






#16 






FIGURE B-9. 


th: 
used to access and synchronize access to the 
Address of the semaphore used to ensure 
exclusive access to the pathname record 


Address of next pathname in linked list 


Number of characters in the file”’s name 


Address of the string containing the file’s | 


name 


Packed record defining file format, record 
format, file usage, and file compression 


Maximum number of characters in a logical 
record 


Boolean indicates if all producers have 
closed on a channel 


Boolean indicates file creation 


Points to a semaphore used to synchronize 
the closing of producers 


Points to a semaphore used 


to synchronize 
the creation of a file | | 


The number of processes writing to a file. 
The number of processes reading a file 
The number of Processes connected to a file 


Address of the unique channel associated 
with this pathname 


IPC PATHNAME RECORD 
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B.4.4 Message Record 


Interprocess communication 
record. 


#00 


buffer 


#02 
length 


#04 
count 





#06 





data is transmitted through a message 





Address of the data to be sent via 
IPC or of the buffer into which data 
is to be received 


Number of total bytes in the message 
field 


Number of bytes actually sent in the 
message field 


FIGURE B-10. IPC MESSAGE RECORD 


B.5 INITIALIZATION OVERVIEW 


The figure that follows presents an overview of system initialization 
via DSINIT. The purpose of this illustration is to tie together many 
of the above data structures. 
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length 
INIT@ 
CONNECT@ 
| opENe 
READ@ 
WRITE@ 
| | CLOSE@ 
; STATUSG 


DISCONNECT@ 


ABORTIOG 
CREATE@ 
DELETE@ 
POSITION@ 


' 
‘ 


node type 


nodename@ 


IOSS 
dependent 
info. 


| 





I/O SUBSYSTEM 
SERVICE DIRECTORY 


STARTED BY GHOSTS PROCESS AT 
POWER UP. 


I/O SERVICE DIRECTORY PRESENT 
IN CONFIG. | 






IOSS 
dependent 
info 


PORT CONSTANTS | 
RECORD 








NODE CONSTANTS 


RECORD 


Cee 





eee 








APPENDIX C 
STATUS AND ERROR MESSAGES 


C.l1 GENERAL 


This section presents error messages generated during execution of the 
File I/0 Decoder. These error messages are at the level of the File 
Identifier Record (FID) denoting error information relative to 
operations on the FID. Three categories of messages are described: 
"Status" information captured in the STATUS field of the FID record 
and returned by the function DSSTATUS, "State" information captured in 
the STATE field of the FID and returned by a call to the function 
DSVALID, and process information which may be examined in the Process 
Descriptor Record. 


Error messages generated during execution of the individual I/0 
Subsystems are unique to each I/O Subsystem. In many instances, a user 
who is returned a FID level error message will need to inspect error 
messages returned by the specific I/O Subsystem. Two ways of obtaining 
this error information are available. If more than one I/O Subsystem 
is operating on the target and the user is unaware of the particular 
I/O Subsystem to be accessed, a call to DSDSTATUS should be made. If 
the appropriate I/O Subsystem is known, a call to the Status function 
in that subsystem can be made. Information on the Status messages at 
the I/O Subsystem level can be obtained from the user manuals 
dedicated to the various I/O Subsystems. . 


C.2 STATUS 


The current status maintained in the FID record field "Status" is 
returned to the user when the File I/0 Decoder function DS$STATUS is 
called. This status information is subsystem independent, defining the 
success or failure of the oldest outstanding request on the FID. 


In general, a status value of 0 indicates that no error condition 
currently exists and no activity is in progress. A non-zero value 
indicates the current status of an outstanding request or the 
existence of an exception condition. Values for the following 
conditions are standarized (device/subsystem independent) : 


_ CODE CONDITION 
0000 Idle or last request complete. No exception 
condition. 
8xxx Request in progress. 
0101 End of File encountered. 





0102 End of information encountered. No more 
information is present on the medium. 


0103 | | End of medium encountered. 


NOTE: The Olxx messages defined above are not exclusive but rather may 
occur together. | 


02x0 File error condition as follows: 


1 | Unsuccessful open 
Unsuccessful read 
Unsuccessful write 
Unsuccessful close 
Unsuccessful disconnect 
Unsuccessful create 
Unsuccessful delete 
Unsuccessful position 
Unsuccessful abortio 
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The user may need to examine the error messages generated at the I/O 
Subsystem level to determine the cause of the 02x0 messages above. 


04x0 Physical data link error on last request as 


defined by subclassifications 1 through 9 above. 


O8xy Illegal state change: x = 0..6 and defines 
present state of FID; y = 0..9 and defines 


operation on FID that was requested but failed ~ 


(y values specify same conditions as x values 
above). For additional information on State, 
refer to Subsection C.3 below. 


C.3 VALID STATE CHANGES 


State information defines the condition of the FID (e.g., Connected, 
Open, Closed, etc.). By calling the File I/O Decoder function DSVALID, 
the user may check for valid state changes. The function returns a 
value of True or False based upon the attempted operation on the FID 
(the call to DSVALID is described in Subsection 3.12.13). If False is 
returned, a call to DSSTATUS should be performed in order to check for 
the specific error (#08xy will be returned as described above). 


Valid State changes are presented in table format below. 
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TABLE C-l. STATE TABLE FOR FILE I/O DECODER 


State Operation on FID 

Pe Conn Create Open Read Posit Write Close Delete Disc 
0. Initial 1 
1 Conn/Close 2 4,5,6 3 0 
2 Created 4,5,6 3 0 
3 Deleted 2 | 0 
4 Open for Rd 4. 4 | | 1 
=) Open for Wt 5 1 
6 Open for R/W 6 6 6 1 


In the above table, the FID states are listed vertically and numbered 
O thru 6. Operations that can be attempted on the FID are indicated to 
the right of each FID state. The numbers to the right of each FID 
state identify the subsequent state of the FID (as idenitified by the 
vertical numbers) after the corresponding FID operation is performed. 
For example, After the FID is connected the FID state changes from 0 
(Initial) to 1 (Connect/Close). After the connected FID is Opened, the 


“FID state is 4, 5, or 6. 


NOTE: the Initial state (assigned 0) is not a true state but rather 
exists merely for documentation purposes. Prior to connection, the FID 
does not exist. Also, after disconnection, the FID does not exist. 


C.4 RUN-TIME SUPPORT ERROR MESSAGES 


The following error messages concerned with the File I/O Decoder and 
I/O Subsystems are generated by the RTS during program execution. 
These errors are captured in the process record of the active process. 


I/O Decoder Errors - Class Code = B 
lL empty file identifier list 


2 file identifier not found 
3 file identifier not released 


Interprocess Communication Errors - Class Code =C 
l no heap for pathname record 
2 no heap for name field 
3 no heap for file variable record 
4 no heap for port variables 
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APPENDIX D 
IMPLEMENTATION OF DUMMY I/O SUBSYSTEMS 


D.-l GENERAL 


The Dummy I/O Subsystem is comprised of a set of dummy routines’ that 
serve two purposes: 


1) Certain services are not meaningful in some subsystems due 
to the nature of the medium associated with the subsystem. 
Often the corresponding service routine in the dummy 
subsystem may be used to provide a "dummy" or "no-op" 
routine that conforms to I/O subsystem interface 
requirements. This substitution is made in the routine 
list of the I/0 Service Directory (Appendix B) of the 
subsystem. For example, IPCSDELETE is not implemented in 
the IPC subsystem (Section IV) since there is no physical 
media to be deleted. If a process references a delete 
routine through the I/O Service Directory, then the dummy 
subsystem routine DUMSDELETE will be invoked. 


2) The Dummy Subsystem also allows producer and consumer 
processes to create and access specific files on which 
most file operations are suppressed. Such ae esystem is 
useful to define "dummy files" in processes. In these 
systems, the messages written to dummy files are consumed 
but. not passed along to other processes. Processes which 
try to read from such files receive end-of-file status. 
This subsystem can be used to "dummy" out file access in 
user applications. 


Routines comprising the dummy subsystem may be invoked as all other 
I/O Subsystem routines (via the File I/O Decoder). Thus, the calling 
sequence for each dummy routine iS compatible with the calling 
sequence for the corresponding routine found in any other subsystem. 
Also, the definition of the use of the parameters in the dummy 


routines is consistent with their definition in all other © 


corresponding subsystem routines. 


The data structures (records) used in the dummy subsystem contain the 
same fields as illustrated in Appendix B ae rewea ng all I/O Subsystem 
data structures). 


D.2 Dummy Routine Descriptions 


The routines comprising the dummy subsystem are described below. The 
routines are considered alphabetically; no calling sequences are 
presented as they are the same as for other I/O Subsystems. The Pascal 
source for each routine is supplied with ;the product. 








D.2.1 Procedure DUMSABORTIO 


This routine will call a wait routine through the I/0 Decoder. The 1/O_ 


Decoder will then reference the appropriate subsystem’s wait routine 
as configured. If the FID is a dummy subsystem File, then the Decoder 
will call DUMSWAIT, which does nothing. 


D.2.2 Procedure DUMSCLOSE 


This routine checks that a file is in a valid state for a call toa 
close routine. If the file is in a valid state, then a wait routine is 
Called through the I/O Decoder to insure that all impending I/0 


operations have completed. DUMSCLOSE then updates the status and state 


of the file and returns. The parameter "with_eof" is not used in this 
system. 


D.2.3 Procedure DUMSCONNECT 


This routine searches the port node records associated with the dummy 
subsystem to determine if the pathname parameters of this routine is 
one that should be connected to the dummy subsystem. If it is, a file 
identifier record is constructed and returned to the caller. 


D.2.4 Procedure DUMSCREATE 


This routine checks that a file is in a valid state for a call to a 
create routine. If the state is valid, then routine will update the 
Status and state of the file. DUMSCREATE performs no create operation 
on the file but was included to provide the dummy subsystem with a 
create routine which has a calling sequence conforming with the create 
call of other I/O subsystems (the only neaningful parameter is the 
FID). | | 


D.2.5 Procedure DUMSDELETE 


This routine checks that a file is in a valid state for a call to a 
delete routine. If the state is valid, then routine will update the 
Status and state of the file. DUMSDELETE performs no delete operation 
on the file but was included to provide the dummy: subsystem with a 
delete routine which has a calling sequence conforming with the delete 
call of other I/O subsystems. 


D.2.6 Procedure DUMSDISCONNECT 


This routine checks that a file is in a valid state for a call to a 
disconnect routine and then deallocates those data structures that are 
associated with a file identifier record. Note that this routine can 


be used by other subsystems if they allocate "fid_ variables” using NEW © 
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and if the fid variable record contains no substructures that require 
special processing to be deallocated. 


D.2.7 Function DUMSDSTATUS 


This function always returns a normal status for the file. DUMSDSTATUS 
performs no status check on the file but was included to provide the 
dummy subsystem with a status routine which has a calling sequence 
conforming with the status call of other I/O subsystems. 


D.2.8 Procedure DUMSINIT 


This routine initializes the subsystem record. 


D.2.9 Procedure DUMSOPEN 


This routine checks that a file is in a valid state for a call to an 
open routine. If the state is valid, then the file is’ opened for 
reading, writing, or both as specified in the parameter "priv". The 
parameters "ft", "logical record_length" and "number_of_records" are 
then initialized to be compatible with a file of variable length 
records with typical length of 80 bytes. 


~-  p.2.10 Procedure DUMSPOSITION 


This routine checks that a file is in a valid state for a call to a 
position routine. If the state is valid, then the routine will update 
the status of the file. DUMSPOSITION performs no position operation on 
the file but was included to provide the dummy subsystem with a 
position routine which has a calling sequence conforming with the 
position call of other I/O subsystems. | 


D.2.11 Procedure DUMSREAD 


This routine checks that a file is in a valid state for a call to a 
read routine. If the state is valid, then the routine will set the 
read parameter "Actual Length" to a default value, and update the 
Status of the file. No actual read will occur and an end-of-file 
Status will always be returned. | 


D.2.12 Procedure DUMSWAIT 


This routine performs no wait operation on a file. DUMSWAIT performs 
no wait operation on the file but was included to provide the dummy 
subsystem with a wait routine which has a calling sequence conforming 
with the wait call of other I/O subsystems. 








D.2.13 Procedure DUMSWRITE 


This routine checks that a file is ina valid state for a call to a 
write routine. If the state is valid, then the routine will update the 
Status of the file. No message is written to a file. 
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APPENDIX E 


FILE ATTRIBUTES FOR USE IN CALLING FILE SERVICE ROUTINES 
E.1l GENERAL 


This appendix contains a discussion of the file attributes described 
by the parameters passed to the File I/O Decoder entry points DSCREATE 
and DSOPEN (detailed in Section III). These entry points are accessed 
(whether directly or via the Pascal primitves) to create and open a 
file for access. 


The file attributes discussed below include file format, record 
format, file compression, access type, access privilege and 
protection, and file names. 


NOTE: Some parameters passed at the file level to define these 

attributes are ignored at the I/O Subsystem level because they are 
Baningless to the node being controlled. (e.g., DSCREATE’S parameter 

Protection Code is ignored by the IPC Subsytem’s Create routine). 


E.2 FILE FORMAT 


File format describes the physical organization of a file and is 
specified at the time the file is created. Contiguous files have a 


fixed file extent. Non-contiguous files have no such fixed length and 


are allowed to grow dynamically up to a maximum of 16 secondary 


-. allocations. Contiguous and non-contiguous files and how they are 


allocated to bulk memory storage are described below. 


E.2.1 Contiguous Files 


When a contiguous file is created, the user specifies the maximum 
number of records to be written in the file and the length in bytes of 
“ach logical record. The number of records is multiplied by logical 
_ecord length to arrive at file extent. 


E.2.2 Non-Contiguous Files 


When ‘a non-contiguous file is created, the user specifies a logical 
record length, an initial number of records to be written in the file, 
and an incremental number of records to expand the file. The primary 
allocation is the product of the primanry number of records and the 
logical record length both rounded up to the nearest multiple of AUs. 
The secondary allocation is the product of the incremental number of 
records and the logical record length. 


The non-contiguous file format allows files to grow dynamically. 
Non-contiguous files can be created small and can be allowed to grow 


“as needed. 








E.-3 RECORD FORMATS 


Record format describes the logical organization of the file and is “> 
specified by the user at_ the time of file creation. Three record ~... 


formats are defined: 


Variable length 
Fixed length 
e Free length 


Each of these formats is examined below. 


E.3.l1 Variable Length 


Variable length records making up a file are logical data structures 
in which the individual record length is not fixed. A variable length 
record format provides an economical way to use file space in 
applications that must record data structures of unpredictable 
lengths. Since the length of the records is a variable, the length of 
each individual record must be recorded along with the record data 
itself. Record headers and trailers are used to contain length 


information and provide record boundaries. The format of variable 


length records supports file compression as discussed in Subsection 
E.4. . 


E.3.2 Fixed Length 


A file of fixed length records consists of copies of logical data 
Structures all of which are exactly the same length. Fixed length 
records facilitate random access; the command to change a file’s 
access position functions more easily on files of fixed length 
records. Ss | 


E.3.3 Free Length 


The free region format allows the user to conceptually subdivide an 
unformatted array of bytes into a structure of his own choosing. In a 
file of free region records, the logical record length is one. 


E.4 FILE COMPRESSION 


File compression is achieved via the surpression of nulls in the 
recording of data contained in files with variable length records. 
Information stored in the record header and trailer results in the 
automatic restoration of nulls when the file”s records are accessed. 
Because of the necessity of header and trailer information, and 
because of the varying . record lengths that can result from file 
compression, file compression cannot be used on files of fixed length 
(or free length) records. 
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E.-5 ACCESS METHODS 


Access methods pertain to the action of recording and retrieving data 
in a file. Access via the DSREAD and DSWRITE routines takes place 
sequentially. Records are processed in order of their increasin 
record numbers on the medium. Random access (processing of a recor 
regardless of its location) can occur by using the DSPOSITION command 
to reposition the file to the desired location. Because of the nature 
of variable and fixed length records, random access proceeds slower on 
the former. 


E.6 ACCESS PRIVILEGE 


Access privilege is requested at the time the file is opened for 
access and establishes a relationship between a user and a data file. 
This relationship specifies what activities the user can perform on 
the file (read, write, execute, and extend as described below) and 
whether or not any other user will be allowed to access the file. The 
user specifies True or False as defined below. 


Exclusion By specifying True, the user gains 
exclusive access to the file or is 
denied access if the file is being 
accessed by another user. 


Reading By specifying True, the user requests 
the capability to read. Whether or 
not others may access depends on the 
"Exclusion" field above. 


Writing By specifying True, the user requests 
the capability to write. If the user 
will be writing to a variable length 
record file, he must specify True to 
the "Exclusion" field. | 


mxecute By specifying True, the user requests 
the capability to execute a program 
file. This option is for possible 
use by operating systems and is not 
Currently supported. | 


Extend — | By specifying True, the user wishes to 
extend the file. 


For each of the above access activities listed, the appropriate 
password is also required to allow user access as described in the 
following subsection. 


“- E.7 ACCESS PROTECTION 











At create time, the user can assign a level of password protection to 
the access activities that can be performed on a file. The parameter 
Protection code defines this protection. For each of four access 
activities, read, write, modify, and execute, a level of password 
proctection can be assigned as follows: 


#1 Unrestricted Access 

#2 User Password needed to access 

#3 Creator password needed to access 
#4 No access | 


where user and creator passwords are defined at the time the file is 
opened. It is possible to access a file with level 2 protection by 
using a Creator Password, since Creator access is a special form of 


User access. 
E.8 FILE NAME 
A special file attribute defined when the file is first connected to 
an 1/0 Subsystem is the file pathname. While this name is I/O 
Subsystem denpendent, the general naming convention is as follows: 
1) A pathname consists of one or more node names. 
2) Each node name consists of up to eight valid ASCII 
characters; a character may be an upper-case alphabetic, a 
numeral, or a dollar sign (“$”%). 


3) The first character in each node name must be alphabetic. 


4) Each node name is separated from other nodes by an ASCII 
period. 
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APPENDIX F 


GLOBAL DECLARATION FILES FOR DIF I/O PACKAGE 


F.1 GENERAL 

Global Declaration Files for the Pascal programmer using DIF I/O 
routines are listed below. Two Global Declaration Files are presented. 
The first is used for Pascal applications requiring the File I/0 
Decoder. The second is used for Pascal applications utilizing the 
Interprocess Communication I/O Subsystem. 

F.2 FILE I/O DECODER GLOBAL DECLARATION FILE 

program dS$declarations; 


const 


dont_care = 2; 


-{ protection type } 


any_access = 1; 

user password = 2; 
creator password = 3; 
no_access = 4; 
max_protection_type = 4; 


{ file format } 
contiguous = 1; 
noncontiguous = 2; 
max file format = 2; 

{ record format |} 
free length = 1; 
variable length = 2; 
fixed_length = 3; 
max record format = 3; 


{ file usage } 


data = l; 

directory = 2; 
allocation_map 
max file usage 


" 
| EN) 
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{ file compression |} 
uncompressed = 1; 
compressed = 2; 

max_file_ compression = 2; 


{ file access mode } 
byte relative = 1; 














sequential = 2; 
direct = 3; 
max file _access_ mode = 3; 


type 


address = integer; 

byte = 0..#FF; 

dummy index _tange = 1..dont care; 

dummy | buffer = packed array[ dummy_index_ range ] of char; 
dummy “buffer ptr = @dummy_ buffer; 

fid = @fid; 7 

hex digit = 0..#F; 


file access _ mode = 1..max_file_access_ mode; | 


file access privilege = packed record 
exclusive_access: boolean; 
read access: boolean; 
Write access: boolean; 
execute access: boolean; 
extend_access: boolean; 
end; 


File type = packed record 
file format: hex digit; 
record _format: hex _digit; 
file _usage: hex _digit; 
file compression: hex digit; 
end; 


password list = record 
‘to be determined 
end: 
password list _ptr = @password_ list; 


protection = packed record 
read protect: hex digit; 
write protect: hex_digit; 
modify protect: hex digit; 
execute protect: hex digit; 
end; 
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procedure dSabortio( f: fid ); external; 
procedure dSclose( f: fid; with_eof: boolean ); external; 


procedure dS$connect( var pathname: dummy buffer; 
length: integer; 


var f: fid ):; external; 
procedure dScreate( f: fid; 
passwords: password list ptr; 
protect: protection; 
ft: file type; 
logical record length: integer; 
initial allocation: longint; 


extension allocation: longint ); external; 
procedure dS$delete( f: fid ); external; 
procedure dS$disconnect( var f: fid ); external; 


procedure dSinit; external; 


procedure dSopen( _ ff: fid; 
passwords: password list ptr; 
mode: file access _ mode; 
priv: file access privilege; 
var ft: | File type; 
var logical record length: integer; 
var number _of_ records: longint ); external; 
procedure dS$position( f: fid; 


relative: boolean; 
number: longint ); external; 


procedure dSrdwait ( f: fid; 
var b: dummy buffer; 
max_length: integer; 


var actual_ length: integer ); external; 


procedure dSread ( f; fid; 
var b: dummy buffer; 
max length: integer; 


Var actual_length: integer ); external; 
| function dS$status( f: fid ): integer; external; | 
procedure dSwait( £: fid ):; external; 

procedure dSwrite ( f: fid; 


var b: dummy buffer; . 
length: integer ); external; 








procedure dS$wrwait ( f: fid; 
: var Db: dummy buffer; 
length: integer ); external; 
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begin 
$ nullbody } 
end. 


F.3 GLOBAL DECLARATION FILE FOR INTERPROCESS COMMUNICATION SUBSYSTEM 


{$ statmap, map } 
program dummySsubsystem; 


const 


bytes per word = 2; 
dont care = 2; 


{ protection type |} 
any_access = l; 
user password = 2; 
creator password = 3; 
no_access = 4; 
max protection type = 4; 


{ file format } | | oes 
contiguous = l; 
noncontiguous = 


23 = 
max file format = 


23 


{ record format } 
free length = 1; 
variable length = 2; 
fixed length = 3; 
max record format = 3; 


{ file usage } 


data = l; 

directory = 2; 
allocation_map 
max file usage 


=e @O 


3 
3 
{ file compression } 
uncompressed = 1; 


compressed = 2; 
max_ file compression = 2; 


{'file access mode } — 
byte relative = 1; 
sequential = 2; 





direct = 3; 
max file_access mode = 3; 


fid state } 
Closed = 1; 
created = 2; 
deleted = 

open _for_reading = 
open for _writing = 
open_for both = 6; 


fid operations } 


Sopen = l; 
Sread = 2; 
Swrite = 3; 


Sdisconnect = 5; 
Screate = 6; 

Sdelete = 7; 

Sposition = 8; | 
max fid operation = 8; 


Sabortio = 9; 
eof encountered = #0101; 


file error = #0200; 

unguecesseul, open = file_error + #10 * Sopen; 
unsuccessful read = file error + #10 * Sread; 
unsuccessful write = file error + #10 * Swrite; 
unsuccessful close = file error + #10 * Sclose; 
unsuccessful disconnect = file error + #10 * $disconnect; 
unsuccessful create = file _error + #10 * Screate; 
unsuccessful delete = file error + #10° * $delete; 
unsuccessful position = file_error + #10 * $position; 
unsuccessful _abortio = file _error + #10 * Sabortio; 


fid_illegal_operation_error = #0800 { + fid operation }; 


normal = 0; 
waiting = #8000 ; 


ipcSerr = 12; 
no_heap_for_pathname_record 

no heap for name field 

no _heap_ for _file _variable record 
no heap for port variables _record 
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type 
rt_ type = ( noneSS, errS, £S$S, hpss, inss, pSs$, cS$, smS$S, 
ipc$$, ct$$, iodss ); 
address = integer; 
byte = 0..#FF; 
dummy index range = 1..dont_care; 
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dummy buffer = packed array[ dummy_index range ] of char; 
dummy~buffer_ptr= @dummy buffer; | 

fid operation = 1l..max_ fid _operation; 

hex digit = 0..#F; 


file access mode = 1..max_file access mode; 


fid = @fid_record; 


£id_variables ptr = @ipc$fid variables record; 


port_constants_ptr = @ipcS$port _constants_record; 
port variables ptr = @ipcSport__ “variables record; 
service _directory _ptr = @service _directory_ record; 
subsystem ptr = @subsystem_ptr; 


-mMemptr = @memptr; 


hp$ = @hp$; 

byte length = 0 .. 32767; 

semaphorestate = ( awaited, zero, signaled )? 
cid = @cid; 


command ptr = @command_record; 
passcode ptr = @passcode_ ptr; 
pathname node ptr = @pathname_node; 
parameters ptr = @ipc$parameters; 


file _access privilege = packed record 
exclusive access: boolean; 
read_access: boolean; 
write access: boolean; 
execute access: boolean; 
extend access: boolean; 
end: 


File type = packed record 
file format: hex digit; 
record _format: hex _digit; 
file usage: hex_digit; 
file | _compression: hex digit; 
end; 


Password = packed array [1..4] of char; 
password ptr = @password; 
Password list = record 

user password: password; 

Creator password: password; 

end; 


Password list_ptr = @password list; 


protection = packed record 
read _ protect: hex digit; 
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write protect: hex_digit; 
modify protect: hex digit; 
execute protect: hex_digit; 
end; 


fid record = record 
link: fid; 
subsystem: subsystem ptr; 
status: integer; 
State: integer; 
fid_variables: fid _variables ptr; 
global __ frame: address; 
end; 


service directory record = record 
length: integer; 
Sinit: address; 
Sconnect: address; 
Sopen: address; 
Sread: address; 
Swrite: address; 
Sclose: address; 
Sstatus: address; 
Sdisconnect: address; 
Sabortio: address; 
Screate: address; 
Sdelete: address; 
Sposition: address; 
Swait: address; 
end; 


ipcSport_constants_record = record 
unused by ipc$ =} 
end; 


ipcSport_variables_ record = record 
mutex: semaphore; 
pathname node: pathname_node_ ptr; 
end: 


command_record = record 
buffer: dummy _ buffer _ ptr; 
length: integer; 
count: integer; 
end; 


ipc$fid variables record = record 
read length ptr: @integer; 
read maxlength: integer; 
read buffer ptr: dummy_buffer_ptr; 
pathname _node: pathname_node_ ptr; 
command: command_ ptr; 
end: 














pathname_node = packed record 
node _mutex: semaphore; | | | | 
link: pathname node ptr; | on 
length: integer; 7 oS 
name: dummy buffer ptr; 
Ft: file type; : 
logical_record length: integer; 
end of production, create called: boolean; 
end_of_ consumption, waiting _for create: semaphore; 
number _of_producers, number of _consumers, 
number connected: integer; 
channel: cid; 
end; 


ipcSparameters = record 
base: integer; 7 
level: integer; 
rate: integer; 
length: integer; 
name: dummy buffer; 
end; 
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common 
Smsg$: fid; 


procedure d$fid ( sub: subsystem ptr; 
fid_vars: fid_variables ptr; 
var f:; fid i external; 
| y 
procedure d$fidrelease( var f: fid ); external; ~ 
procedure dSsubsystenm ( serv: service directory ptr; 
port cons: port_constants ptr; | 
port vars: port variables ptr; , 
var sub: subsystem ptr ); external; | 
’function d$valid( f: fid; | 
op: fid_operation ): boolean; external; 
procedure ipcSclose( f: fid; close with eof: boolean ); forward; 
procedure ipc$connect ( sub: subsystem ptr; ; 
var pathname: dummy_buffer; 
length: integer; 
var €£: Fid ); forward; 
procedure ipcScreate( f: fid; 
passwords: password list ptr; 
Protect: | protection; 
ft: file ‘type; 
logical_record length: integer; 
initial allocation: longint; 


extension_allocation: longint ); forward; 


procedure ipcSdisconnect( var f: fid ); forward; 


procedure ipcSinit ( serv: service directory ptr; 
| port cons: port _constants_ ptr; | 
var sub: | subsystem _ptr ); forward; 
procedure ipcSopen ( f: fid; 
password: password ptr; 
mode : file access mode; 
priv: file access privilege; 
var ft: file type; 
var logical_record length: integer; 
var number of records: longint ); forward; 
procedure ipcSread ( fs: fid; 
| bs dummy buffer ptr; 
max_length: integer; 


var actual_length: integer ); forward; 
procedure ipcSwait( f£: fid ); forward; 


procedure ipcSwrite( f: fid; 
bs dummy buffer ptr; 
length: integer ); forward; 


procedure cwait( s: semaphore; var received: boolean ); external; 
function cksemaphore( s: semaphore ): boolean; external; 

procedure initsemaphore( var s: semaphore; count: integer ); external; 
procedure signal( s: semaphore ); external; 

function semastate( sema: semaphore ): semaphorestate; external; . 
procedure termsemaphore( var s: semaphore ); external; 

procedure wait( s: semaphore ); external; 

procedure waitsignal( waitfor, signalthe : semaphore ); external; 


procedure exception( classcode, reasoncode: integer ); external; 
procedure rtSenter( typ: rt_type; abstract object: address ); external; 
procedure rtSexit; external; 
function eqSnames (var namel: dummy buffer; lengthl: integer; 

name2: dummy buffer _ ptr; length2: integer ): boolean; external; 


procedure hpSfree (heap: hp$: var ptr: memptr); forward; 

procedure hp$new(heap: hp$: var ptr: memptr; length: byte rengen)? 
forward; 

function hpSsystem: hpS; forward; 


procedure cSacknowledge( cmd: command_ptr ); external; 

procedure cSallocate( msg_size: integer; var cmd: command ptr ); 
external;. 

Procedure cScreceive( c: cid; var cmd: command _ptr ); external; 

procedure cS$dispose ( var cmd: command ptr ); external; 

procedure cSinit( i: integer; var c: cid ); external; 

procedure cSreceive( c: cid; var cmd: command ptr ); external; 
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procedure c$send( c: cid; cmd: command_ptr ); external; 
procedure cS$term( var c: cid ); external; 

procedure cSwait( cmd: command_ptr ); external; 

begin | 

{$ nullbody } 
nd 
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